@lucern/sdk 0.2.0-alpha.5 → 0.2.0-alpha.7

package/src/events.ts

@@ -0,0 +1,531 @@
+export const DOMAIN_EVENT_VERSION = "1.0" as const;
+export const EVENT_RETENTION_DEFAULT_DAYS = 30;
+export const WEBHOOK_MAX_ATTEMPTS = 5;
+export const WEBHOOK_RETRY_DELAYS_MS = [1_000, 5_000, 30_000, 300_000] as const;
+
+export const DOMAIN_EVENT_TYPES = [
+  "belief.created",
+  "belief.forked",
+  "belief.confidence_updated",
+  "belief.archived",
+  "belief.refined",
+  "belief.contract_created",
+  "belief.contract_evaluated",
+  "belief.lineage_queried",
+  "evidence.created",
+  "evidence.linked",
+  "evidence.search_executed",
+  "question.created",
+  "question.answered",
+  "question.refined",
+  "question.status_updated",
+  "question.archived",
+  "edge.created",
+  "contradiction.flagged",
+  "worktree.created",
+  "worktree.activated",
+  "worktree.merged",
+  "worktree.targets_updated",
+  "worktree.metadata_updated",
+  "topic.created",
+  "topic.updated",
+  "topic.archived",
+  "task.created",
+  "task.completed",
+  "task.updated",
+  "ontology.bound",
+  "context.compiled",
+  "identity.key_created",
+  "identity.key_rotated",
+  "identity.key_revoked",
+  "webhook.test",
+] as const;
+
+export type DomainEventType = (typeof DOMAIN_EVENT_TYPES)[number];
+
+export type DomainResourceType =
+  | "belief"
+  | "evidence"
+  | "question"
+  | "edge"
+  | "contradiction"
+  | "worktree"
+  | "topic"
+  | "task"
+  | "ontology"
+  | "context"
+  | "identity"
+  | "webhook";
+
+export type DomainActorType = "human" | "agent" | "service";
+export type DomainEventData = Record<string, unknown>;
+
+export type DomainEvent = {
+  eventId: string;
+  type: DomainEventType | string;
+  version: typeof DOMAIN_EVENT_VERSION;
+  timestamp: number;
+  tenantId?: string;
+  workspaceId?: string;
+  topicId: string;
+  resourceId: string;
+  resourceType: DomainResourceType | string;
+  actorId: string;
+  actorType: DomainActorType;
+  data: DomainEventData;
+  correlationId?: string;
+  expiresAt: number;
+};
+
+export type CreateDomainEventInput = {
+  eventId?: string;
+  timestamp?: number;
+  tenantId?: string;
+  workspaceId?: string;
+  topicId: string;
+  type: DomainEventType | string;
+  resourceId: string;
+  resourceType: DomainResourceType | string;
+  actorId: string;
+  actorType: DomainActorType;
+  data?: DomainEventData;
+  correlationId?: string;
+  retentionDays?: number;
+};
+
+export type EventCursor = {
+  timestamp: number;
+  eventId: string;
+};
+
+export type EventListQuery = {
+  topicId?: string;
+  after?: string;
+  types?: string[];
+  startTime?: number;
+  endTime?: number;
+  limit?: number;
+};
+
+export type EventListResult = {
+  events: DomainEvent[];
+  nextCursor: string | null;
+};
+
+export type WebhookSecretMode = "configured";
+
+export type WebhookRecord = {
+  id: string;
+  webhookId: string;
+  tenantId?: string;
+  workspaceId?: string;
+  topicId?: string;
+  url: string;
+  events: string[];
+  active: boolean;
+  secretConfigured: boolean;
+  createdAt: number;
+  updatedAt: number;
+  createdBy: string;
+  updatedBy: string;
+  lastDeliveryAt?: number;
+  lastSuccessfulDeliveryAt?: number;
+};
+
+export type WebhookCreateInput = {
+  url: string;
+  events: string[];
+  secret: string;
+  topicId?: string;
+  active?: boolean;
+};
+
+export type WebhookUpdateInput = {
+  url?: string;
+  events?: string[];
+  secret?: string;
+  topicId?: string | null;
+  active?: boolean;
+};
+
+export type WebhookDeliveryStatus =
+  | "pending"
+  | "delivering"
+  | "succeeded"
+  | "failed"
+  | "dead_letter";
+
+export type WebhookDeliveryRecord = {
+  id: string;
+  deliveryId: string;
+  webhookId: string;
+  eventId: string;
+  eventType: string;
+  topicId: string;
+  status: WebhookDeliveryStatus;
+  attemptCount: number;
+  maxAttempts: number;
+  nextAttemptAt?: number;
+  lastAttemptAt?: number;
+  lastStatusCode?: number;
+  lastError?: string;
+  deliveredAt?: number;
+  createdAt: number;
+  updatedAt: number;
+};
+
+export type WebhookDeliveryAttemptRecord = {
+  id: string;
+  attemptId: string;
+  deliveryId: string;
+  webhookId: string;
+  eventId: string;
+  eventType: string;
+  attemptNumber: number;
+  status: "succeeded" | "failed";
+  statusCode?: number;
+  error?: string;
+  responseBody?: string;
+  durationMs?: number;
+  createdAt: number;
+};
+
+export type WebhookDeliveriesResult = {
+  deliveries: Array<
+    WebhookDeliveryRecord & {
+      attempts?: WebhookDeliveryAttemptRecord[];
+    }
+  >;
+};
+
+export type WebhookHealthResult = {
+  webhookId: string;
+  totalAttempts: number;
+  successfulAttempts: number;
+  failedAttempts: number;
+  successRate: number;
+  pendingDeliveries: number;
+  deadLetterDeliveries: number;
+  lastDeliveryAt?: number;
+  lastSuccessfulDeliveryAt?: number;
+};
+
+export type WebhookTestResult = {
+  webhookId: string;
+  deliveryId: string;
+  status: WebhookDeliveryStatus;
+  attempts: number;
+};
+
+export type ReplayEventsInput = EventListQuery & {
+  webhookId?: string;
+};
+
+export type ReplayEventsResult = EventListResult & {
+  replayedDeliveries?: number;
+  replayedWebhookId?: string;
+};
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function eventPatternToRegExp(pattern: string): RegExp {
+  const normalized = pattern.trim();
+  if (!normalized) {
+    return /^$/;
+  }
+  if (normalized === "*") {
+    return /^.*$/;
+  }
+  const source = escapeRegex(normalized).replace(/\\\*/g, ".*");
+  return new RegExp(`^${source}$`);
+}
+
+export function matchesEventPattern(
+  eventType: string,
+  pattern: string
+): boolean {
+  return eventPatternToRegExp(pattern).test(eventType.trim());
+}
+
+export function matchesAnyEventPattern(
+  eventType: string,
+  patterns: readonly string[]
+): boolean {
+  if (patterns.length === 0) {
+    return true;
+  }
+  return patterns.some((pattern) => matchesEventPattern(eventType, pattern));
+}
+
+function toBase64(value: string): string {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(value, "utf8").toString("base64url");
+  }
+  return btoa(unescape(encodeURIComponent(value)))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/g, "");
+}
+
+function fromBase64(value: string): string {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(value, "base64url").toString("utf8");
+  }
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  return decodeURIComponent(escape(atob(normalized)));
+}
+
+export function createEventId(): string {
+  const random =
+    typeof globalThis.crypto?.randomUUID === "function"
+      ? globalThis.crypto.randomUUID().replace(/-/g, "")
+      : Array.from(
+          typeof globalThis.crypto?.getRandomValues === "function"
+            ? globalThis.crypto.getRandomValues(new Uint8Array(16))
+            : Array.from({ length: 16 }, () => Math.floor(Math.random() * 256)),
+          (value) => value.toString(16).padStart(2, "0")
+        ).join("");
+  return `evt_${random}`;
+}
+
+export function normalizeRetentionDays(value: number | undefined): number {
+  if (!Number.isFinite(value) || typeof value !== "number" || value <= 0) {
+    return EVENT_RETENTION_DEFAULT_DAYS;
+  }
+  return Math.max(1, Math.trunc(value));
+}
+
+export function buildDomainEvent(input: CreateDomainEventInput): DomainEvent {
+  const timestamp = input.timestamp ?? Date.now();
+  const retentionDays = normalizeRetentionDays(input.retentionDays);
+  return {
+    eventId: input.eventId?.trim() || createEventId(),
+    type: input.type.trim(),
+    version: DOMAIN_EVENT_VERSION,
+    timestamp,
+    tenantId: input.tenantId?.trim() || undefined,
+    workspaceId: input.workspaceId?.trim() || undefined,
+    topicId: input.topicId.trim(),
+    resourceId: input.resourceId.trim(),
+    resourceType: input.resourceType.trim(),
+    actorId: input.actorId.trim(),
+    actorType: input.actorType,
+    data: input.data ?? {},
+    correlationId: input.correlationId?.trim() || undefined,
+    expiresAt: timestamp + retentionDays * 24 * 60 * 60 * 1000,
+  };
+}
+
+export function compareEventCursor(left: EventCursor, right: EventCursor): number {
+  if (left.timestamp !== right.timestamp) {
+    return left.timestamp - right.timestamp;
+  }
+  return left.eventId.localeCompare(right.eventId);
+}
+
+export function encodeEventCursor(cursor: EventCursor): string {
+  return toBase64(JSON.stringify(cursor));
+}
+
+export function decodeEventCursor(cursor: string | undefined): EventCursor | null {
+  if (!cursor || cursor.trim().length === 0) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fromBase64(cursor.trim())) as Partial<EventCursor>;
+    if (
+      typeof parsed.timestamp !== "number" ||
+      !Number.isFinite(parsed.timestamp) ||
+      typeof parsed.eventId !== "string" ||
+      parsed.eventId.trim().length === 0
+    ) {
+      return null;
+    }
+    return {
+      timestamp: parsed.timestamp,
+      eventId: parsed.eventId.trim(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function isAfterCursor(
+  event: Pick<DomainEvent, "timestamp" | "eventId">,
+  cursor: EventCursor | null
+): boolean {
+  if (!cursor) {
+    return true;
+  }
+  return compareEventCursor(event, cursor) > 0;
+}
+
+export function sortEventsByCursor<T extends Pick<DomainEvent, "timestamp" | "eventId">>(
+  events: readonly T[]
+): T[] {
+  return [...events].sort((left, right) => compareEventCursor(left, right));
+}
+
+export function inferActorType(args: {
+  sessionType?: "agent" | "user";
+  authMode?: string;
+  principalType?: string;
+}): DomainActorType {
+  if (args.sessionType === "agent") {
+    return "agent";
+  }
+  if (
+    args.authMode === "service_principal" ||
+    args.authMode === "tenant_api_key" ||
+    args.principalType === "service"
+  ) {
+    return "service";
+  }
+  return "human";
+}
+
+export async function emitDomainEvent(
+  invokeMutation: (reference: any, args: CreateDomainEventInput) => Promise<unknown>,
+  input: CreateDomainEventInput
+): Promise<unknown> {
+  return await invokeMutation("events:recordEvent" as any, input);
+}
+
+const LOCALHOST_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+
+function normalizeUrl(url: string): URL {
+  try {
+    return new URL(url.trim());
+  } catch {
+    throw new Error("Webhook URL must be a valid absolute URL.");
+  }
+}
+
+export function assertValidWebhookUrl(url: string): string {
+  const parsed = normalizeUrl(url);
+  const hostname = parsed.hostname.trim().toLowerCase();
+  const nodeEnv =
+    typeof process !== "undefined" ? process.env?.NODE_ENV : undefined;
+  const allowLocalHttp =
+    nodeEnv === "test" || LOCALHOST_HOSTS.has(hostname);
+
+  if (parsed.protocol !== "https:" && !(allowLocalHttp && parsed.protocol === "http:")) {
+    throw new Error("Webhook URL must use HTTPS.");
+  }
+
+  return parsed.toString();
+}
+
+export function normalizeWebhookPatterns(patterns: readonly string[]): string[] {
+  const normalized = Array.from(
+    new Set(
+      patterns
+        .map((pattern) => pattern.trim())
+        .filter((pattern) => pattern.length > 0)
+    )
+  );
+
+  if (normalized.length === 0) {
+    throw new Error("At least one webhook event pattern is required.");
+  }
+
+  return normalized;
+}
+
+export function assertValidWebhookSecret(secret: string): string {
+  const normalized = secret.trim();
+  if (normalized.length < 8) {
+    throw new Error("Webhook secret must be at least 8 characters.");
+  }
+  return normalized;
+}
+
+export async function computeWebhookSignature(
+  payload: string,
+  secret: string
+): Promise<string> {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+  return Array.from(new Uint8Array(signature))
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+export function nextDeliveryAttemptAt(
+  currentAttemptCount: number,
+  now = Date.now()
+): number | undefined {
+  if (currentAttemptCount >= WEBHOOK_MAX_ATTEMPTS) {
+    return undefined;
+  }
+  const retryIndex = currentAttemptCount - 1;
+  const delay = WEBHOOK_RETRY_DELAYS_MS[retryIndex];
+  return typeof delay === "number" ? now + delay : undefined;
+}
+
+export function resolveDeliveryFailureStatus(
+  attemptCount: number
+): WebhookDeliveryStatus {
+  return attemptCount >= WEBHOOK_MAX_ATTEMPTS ? "dead_letter" : "failed";
+}
+
+export function sanitizeWebhookRecord(
+  value: Record<string, unknown>
+): WebhookRecord {
+  return {
+    id: String(value.id ?? value.webhookId ?? value._id ?? ""),
+    webhookId: String(value.webhookId ?? value.id ?? value._id ?? ""),
+    tenantId:
+      typeof value.tenantId === "string" && value.tenantId.trim().length > 0
+        ? value.tenantId
+        : undefined,
+    workspaceId:
+      typeof value.workspaceId === "string" && value.workspaceId.trim().length > 0
+        ? value.workspaceId
+        : undefined,
+    topicId:
+      typeof value.topicId === "string" && value.topicId.trim().length > 0
+        ? value.topicId
+        : undefined,
+    url: String(value.url ?? ""),
+    events: Array.isArray(value.events)
+      ? value.events
+          .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+          .filter(Boolean)
+      : [],
+    active: value.active !== false,
+    secretConfigured: true,
+    createdAt: Number(value.createdAt ?? Date.now()),
+    updatedAt: Number(value.updatedAt ?? value.createdAt ?? Date.now()),
+    createdBy: String(value.createdBy ?? ""),
+    updatedBy: String(value.updatedBy ?? value.createdBy ?? ""),
+    lastDeliveryAt:
+      typeof value.lastDeliveryAt === "number" ? value.lastDeliveryAt : undefined,
+    lastSuccessfulDeliveryAt:
+      typeof value.lastSuccessfulDeliveryAt === "number"
+        ? value.lastSuccessfulDeliveryAt
+        : undefined,
+  };
+}
+
+export function truncateWebhookResponseBody(
+  responseBody: string | undefined,
+  maxLength = 2_000
+): string | undefined {
+  if (!responseBody) {
+    return undefined;
+  }
+  if (responseBody.length <= maxLength) {
+    return responseBody;
+  }
+  return `${responseBody.slice(0, maxLength - 3)}...`;
+}

package/src/eventsCore.ts

@@ -0,0 +1,168 @@
+import {
+  createGatewayRequestClient,
+  randomIdempotencyKey,
+  toQueryString,
+  type GatewayClientConfig,
+  type PlatformGatewaySuccess,
+} from "./coreClient";
+import type {
+  EventListQuery,
+  EventListResult,
+  ReplayEventsInput,
+  ReplayEventsResult,
+  WebhookCreateInput,
+  WebhookDeliveriesResult,
+  WebhookHealthResult,
+  WebhookRecord,
+  WebhookTestResult,
+  WebhookUpdateInput,
+} from "./events";
+import type { JsonObject } from "./types";
+
+export type EventsClientCoreConfig = GatewayClientConfig;
+export type EventsListResponse = PlatformGatewaySuccess<EventListResult>;
+export type EventsReplayResponse = PlatformGatewaySuccess<ReplayEventsResult>;
+
+export type WebhooksClientCoreConfig = GatewayClientConfig;
+export type WebhookListQuery = {
+  topicId?: string;
+};
+export type WebhookDeliveriesQuery = {
+  limit?: number;
+};
+export type WebhookDeleteResult = {
+  webhookId: string;
+  deleted: boolean;
+};
+export type WebhooksCreateResponse = PlatformGatewaySuccess<WebhookRecord>;
+export type WebhooksListResponse = PlatformGatewaySuccess<{ webhooks: WebhookRecord[] }>;
+export type WebhooksGetResponse = PlatformGatewaySuccess<WebhookRecord>;
+export type WebhooksUpdateResponse = PlatformGatewaySuccess<WebhookRecord>;
+export type WebhooksDeleteResponse = PlatformGatewaySuccess<WebhookDeleteResult>;
+export type WebhooksTestResponse = PlatformGatewaySuccess<WebhookTestResult>;
+export type WebhooksDeliveriesResponse =
+  PlatformGatewaySuccess<WebhookDeliveriesResult>;
+export type WebhooksHealthResponse = PlatformGatewaySuccess<WebhookHealthResult>;
+
+function serializeTypes(types: string[] | undefined) {
+  return Array.isArray(types) && types.length > 0 ? types.join(",") : undefined;
+}
+
+export function createEventsClientCore(config: EventsClientCoreConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    async list(query: EventListQuery = {}): Promise<EventsListResponse> {
+      return gateway.request<EventListResult>({
+        path: `/v1/events${toQueryString({
+          topicId: query.topicId,
+          after: query.after,
+          types: serializeTypes(query.types),
+          startTime: query.startTime,
+          endTime: query.endTime,
+          limit: query.limit,
+        })}`,
+      });
+    },
+
+    async replay(
+      input: ReplayEventsInput,
+      idempotencyKey = randomIdempotencyKey()
+    ): Promise<EventsReplayResponse> {
+      return gateway.request<ReplayEventsResult>({
+        path: "/v1/events/replay",
+        method: "POST",
+        body: input as JsonObject,
+        idempotencyKey,
+      });
+    },
+  };
+}
+
+export function createWebhooksClientCore(
+  config: WebhooksClientCoreConfig = {}
+) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    async create(
+      input: WebhookCreateInput,
+      idempotencyKey = randomIdempotencyKey()
+    ): Promise<WebhooksCreateResponse> {
+      return gateway.request<WebhookRecord>({
+        path: "/v1/webhooks",
+        method: "POST",
+        body: input as JsonObject,
+        idempotencyKey,
+      });
+    },
+
+    async list(query: WebhookListQuery = {}): Promise<WebhooksListResponse> {
+      return gateway.request<{ webhooks: WebhookRecord[] }>({
+        path: `/v1/webhooks${toQueryString({
+          topicId: query.topicId,
+        })}`,
+      });
+    },
+
+    async get(id: string): Promise<WebhooksGetResponse> {
+      return gateway.request<WebhookRecord>({
+        path: `/v1/webhooks/${encodeURIComponent(id)}`,
+      });
+    },
+
+    async update(
+      id: string,
+      input: WebhookUpdateInput,
+      idempotencyKey = randomIdempotencyKey()
+    ): Promise<WebhooksUpdateResponse> {
+      return gateway.request<WebhookRecord>({
+        path: `/v1/webhooks/${encodeURIComponent(id)}`,
+        method: "PATCH",
+        body: input as JsonObject,
+        idempotencyKey,
+      });
+    },
+
+    async delete(
+      id: string,
+      idempotencyKey = randomIdempotencyKey()
+    ): Promise<WebhooksDeleteResponse> {
+      return gateway.request<WebhookDeleteResult>({
+        path: `/v1/webhooks/${encodeURIComponent(id)}`,
+        method: "DELETE",
+        idempotencyKey,
+      });
+    },
+
+    async test(
+      id: string,
+      input: { topicId?: string } = {},
+      idempotencyKey = randomIdempotencyKey()
+    ): Promise<WebhooksTestResponse> {
+      return gateway.request<WebhookTestResult>({
+        path: `/v1/webhooks/${encodeURIComponent(id)}/test`,
+        method: "POST",
+        body: input as JsonObject,
+        idempotencyKey,
+      });
+    },
+
+    async deliveries(
+      id: string,
+      query: WebhookDeliveriesQuery = {}
+    ): Promise<WebhooksDeliveriesResponse> {
+      return gateway.request<WebhookDeliveriesResult>({
+        path: `/v1/webhooks/${encodeURIComponent(id)}/deliveries${toQueryString({
+          limit: query.limit,
+        })}`,
+      });
+    },
+
+    async health(id: string): Promise<WebhooksHealthResponse> {
+      return gateway.request<WebhookHealthResult>({
+        path: `/v1/webhooks/${encodeURIComponent(id)}/health`,
+      });
+    },
+  };
+}