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

package/src/events.ts

@@ -1,531 +0,0 @@
-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

@@ -1,168 +0,0 @@
-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`,
-      });
-    },
-  };
-}