@asaidimu/hestia 1.0.0

package/system/logs/store.ts

@@ -0,0 +1,147 @@
+import type { QueryDSL } from "@asaidimu/query"
+import { HestiaNetworkClient } from "../../core/client"
+import type { Page, PaginationInfo } from "../../core/types"
+import type { AuditEntry } from "./types"
+
+interface FindEnvelope {
+  data: AuditEntry[]
+  metadata?: { page?: PaginationInfo }
+}
+
+interface StreamDoc {
+  data: AuditEntry
+}
+
+export class HestiaLogs {
+  constructor(
+    private client: HestiaNetworkClient,
+    private baseUrl: string,
+  ) {}
+
+  async find(query?: QueryDSL<AuditEntry>): Promise<Page<AuditEntry>> {
+    const res = await this.client.post<FindEnvelope>(
+      "/system/audit/log/query",
+      { query: query ?? {} },
+    )
+
+    const items = res.data?.data ?? []
+    const pageMeta = res.data?.metadata?.page ?? {
+      number: 1,
+      size: items.length,
+      count: items.length,
+      total: items.length,
+      pages: 1,
+    }
+
+    return { data: items, loading: false, page: pageMeta, error: null }
+  }
+
+  async list(): Promise<Page<AuditEntry>> {
+    return this.find({
+      pagination: { type: "offset", offset: 0, limit: 20 },
+    })
+  }
+
+  getStreamUrl(): string {
+    return `${this.baseUrl}/system/audit/log/stream`
+  }
+
+  subscribe(onEntry: (entry: AuditEntry) => void): () => void {
+    const url = this.getStreamUrl()
+    const eventSource = new EventSource(url, { withCredentials: true })
+
+    eventSource.onmessage = (event) => {
+      try {
+        const parsed = JSON.parse(event.data) as StreamDoc
+        if (parsed?.data) {
+          onEntry(parsed.data)
+        }
+      } catch {
+        // skip non-JSON lines
+      }
+    }
+
+    eventSource.onerror = () => {
+      eventSource.close()
+    }
+
+    return () => {
+      eventSource.close()
+    }
+  }
+
+  stream(): {
+    stream: () => AsyncIterable<AuditEntry>
+    cancel: () => void
+    status: () => "active" | "cancelled" | "completed"
+  } {
+    const url = this.getStreamUrl()
+    let eventSource: EventSource | null = null
+    let currentStatus: "active" | "cancelled" | "completed" = "active"
+    let pendingResolve: (() => void) | null = null
+
+    const asyncStream = async function* () {
+      const pending: AuditEntry[] = []
+
+      eventSource = new EventSource(url, { withCredentials: true })
+
+      eventSource.onmessage = (event) => {
+        for (const line of event.data.split("\n")) {
+          const trimmed = line.trim()
+          if (!trimmed) continue
+          try {
+            const parsed = JSON.parse(trimmed) as StreamDoc
+            if (parsed?.data) pending.push(parsed.data)
+          } catch {
+            // skip non-JSON lines
+          }
+        }
+        if (pending.length > 0 && pendingResolve) {
+          pendingResolve()
+          pendingResolve = null
+        }
+      }
+
+      eventSource.onerror = () => {
+        if (currentStatus === "active") currentStatus = "completed"
+        if (pendingResolve) {
+          pendingResolve()
+          pendingResolve = null
+        }
+      }
+
+      try {
+        while (currentStatus === "active") {
+          if (pending.length > 0) {
+            yield pending.shift()!
+          } else {
+            await new Promise<void>((resolve) => {
+              pendingResolve = resolve
+              if (pending.length > 0) {
+                resolve()
+                pendingResolve = null
+              }
+            })
+          }
+        }
+      } finally {
+        eventSource?.close()
+        if (pendingResolve) {
+          pendingResolve()
+          pendingResolve = null
+        }
+        if (currentStatus === "active") currentStatus = "completed"
+      }
+    }
+
+    return {
+      stream: () => asyncStream(),
+      cancel: () => {
+        if (currentStatus !== "active") return
+        currentStatus = "cancelled"
+        eventSource?.close()
+      },
+      status: () => currentStatus,
+    }
+  }
+}

package/system/logs/types.ts

@@ -0,0 +1,38 @@
+export interface AuditEntry {
+  event_id: string
+  occurred_at: string
+  recorded_at: string
+  trace_id?: string
+  request_id?: string
+  actor_id: string
+  actor_type: "user" | "service" | "system" | "anonymous"
+  on_behalf_of_id?: string
+  auth_method?: "password" | "oauth" | "api_key" | "mtls" | "sso" | "service_account" | "none"
+  session_id?: string
+  operation: "create" | "read" | "update" | "delete" | "login" | "logout" | "grant" | "revoke" | "execute" | "other"
+  resource_type: string
+  resource_id?: string
+  event_name: string
+  status: "success" | "failure" | "denied" | "error"
+  severity?: "info" | "warning" | "critical"
+  error_code?: string
+  error_message?: string
+  latency_ms: number
+  source_ip?: string
+  user_agent?: string
+  service_name: string
+  region?: string
+}
+
+export type RequestLogEntry = AuditEntry
+
+export interface LogFilter {
+  actor_id?: string
+  actor_type?: string
+  operation?: string
+  status?: string
+  resource_type?: string
+  trace_id?: string
+  start?: string
+  end?: string
+}

package/system/policies/store.ts

@@ -0,0 +1,74 @@
+import type { QueryDSL } from "@asaidimu/query"
+import { HestiaNetworkClient } from "../../core/client"
+import { HestiaCollection } from "../../core/collection"
+import type { Document, Page } from "../../core/types"
+import type {
+    PolicyOperation,
+    PolicyRule,
+    UpsertOperationRequest,
+    UpsertRuleRequest,
+} from "./types"
+
+export class HestiaPolicies {
+  private operations: HestiaCollection<PolicyOperation>
+  private rules: HestiaCollection<PolicyRule>
+
+  constructor(private client: HestiaNetworkClient) {
+    this.operations = new HestiaCollection<PolicyOperation>(client, "_policy_operation_")
+    this.rules = new HestiaCollection<PolicyRule>(client, "_policy_rule_")
+  }
+
+  // ── Operations ──
+
+  async findOperations(query?: QueryDSL<PolicyOperation>): Promise<Page<PolicyOperation>> {
+    return this.operations.find(query)
+  }
+
+  async listOperations(): Promise<Page<PolicyOperation>> {
+    return this.operations.find({ pagination: { type: "offset", offset: 0, limit: 50 } })
+  }
+
+  async readOperation(name: string): Promise<Document<PolicyOperation> | undefined> {
+    return this.operations.read(name)
+  }
+
+  async createOperation(data: UpsertOperationRequest): Promise<Document<PolicyOperation>> {
+    return this.operations.create(data as any)
+  }
+
+  async updateOperation(name: string, data: UpsertOperationRequest): Promise<Document<PolicyOperation>> {
+    return this.operations.update(name, data as any)
+  }
+
+  async deleteOperation(name: string): Promise<void> {
+    return this.operations.delete(name)
+  }
+
+  // ── Rules ──
+
+  async findRules(query?: QueryDSL<PolicyRule>): Promise<Page<PolicyRule>> {
+    return this.rules.find(query)
+  }
+
+  async listRules(): Promise<Page<PolicyRule>> {
+    return this.rules.find({ pagination: { type: "offset", offset: 0, limit: 50 } })
+  }
+
+  async readRule(name: string): Promise<Document<PolicyRule> | undefined> {
+    return this.rules.read(name)
+  }
+
+  async createRule(data: UpsertRuleRequest): Promise<Document<PolicyRule>> {
+    return this.rules.create(data as any)
+  }
+
+  async updateRule(name: string, data: UpsertRuleRequest): Promise<Document<PolicyRule>> {
+    return this.rules.update(name, data as any)
+  }
+
+  async deleteRule(name: string): Promise<void> {
+    return this.rules.delete(name)
+  }
+
+
+}

package/system/policies/types.ts

@@ -0,0 +1,43 @@
+export interface PolicyOperation {
+  name: string
+  ruleKey: string
+  description?: string
+  intentType?: "COMMAND" | "QUERY"
+}
+
+export interface UpsertOperationRequest {
+  ruleKey: string
+  description?: string
+  intentType?: "COMMAND" | "QUERY"
+}
+
+export interface PolicyRule {
+  name: string
+  ruleType?: string
+  expression?: string
+  description?: string
+}
+
+export interface UpsertRuleRequest {
+  expression: string
+  ruleType?: string
+  description?: string
+}
+
+export interface ValidateRuleRequest {
+  expression: string
+  identity?: Record<string, unknown>
+  resource?: Record<string, unknown>
+  environment?: Record<string, unknown>
+}
+
+export interface ValidateRuleResult {
+  valid: boolean
+  compile?: string
+  result?: boolean
+}
+
+export interface ReloadResult {
+  operations: number
+  rules: number
+}

package/test-setup.ts

@@ -0,0 +1,53 @@
+import { spawn, type ChildProcess } from "child_process"
+import { resolve } from "path"
+
+const PROJECT_ROOT = resolve(import.meta.dirname, "..")
+const SERVER_BIN = resolve(PROJECT_ROOT, "test-server")
+const START_TIMEOUT = 30000
+
+let serverProc: ChildProcess | null = null
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms))
+}
+
+export async function setup(): Promise<void> {
+  await new Promise<void>((resolvePromise, reject) => {
+    serverProc = spawn(SERVER_BIN, [], {
+      cwd: PROJECT_ROOT,
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+
+    let started = false
+    const onData = (data: Buffer) => {
+      const text = data.toString().trim()
+      if (!started && /^\d+$/.test(text)) {
+        started = true
+        resolvePromise()
+      }
+    }
+
+    serverProc.stdout!.on("data", onData)
+    serverProc.stderr!.on("data", () => {})
+
+    serverProc.on("error", (err) => {
+      if (!started) reject(err)
+    })
+    serverProc.on("exit", (code) => {
+      if (!started) reject(new Error(`server exited with code ${code} before ready`))
+    })
+
+    setTimeout(() => {
+      if (!started) reject(new Error("server start timeout"))
+    }, START_TIMEOUT)
+  })
+
+  await sleep(1000)
+}
+
+export async function teardown(): Promise<void> {
+  if (serverProc && !serverProc.killed) {
+    serverProc.kill("SIGTERM")
+    serverProc = null
+  }
+}

package/utils/index.ts

@@ -0,0 +1 @@
+export * from "./pager"

package/utils/pager.ts

@@ -0,0 +1,226 @@
+import { QueryDSL, QueryFilter, SortConfiguration, createMatcher, createSorter } from '@asaidimu/query'; //
+import { DELETE_SYMBOL, ReactiveDataStore } from "@asaidimu/utils-store"; //
+import { Page, PagedData } from '../core/types';
+
+export interface FetchResult<T extends Record<string, any>> {
+  data: T[];
+  replace: boolean;
+  scope: 'page' | 'collection';
+  total?: number;
+}
+
+// Extensible parameters object embracing your DataStore infra
+export interface ArrayPagerOptions<T extends Record<string, any>, F = any> {
+  collectionName: string; // Unique identifier used to partition the cache matrix
+  initialData?: T[];
+  page?: number;
+  size?: number;
+  customFunctions?: Record<string, (...args: any[]) => boolean>;
+  fetch?: (
+    query: QueryDSL<T, F>
+  ) => Promise<FetchResult<T>> | FetchResult<T>;
+}
+
+export function createArrayPager<T extends Record<string, any>, F = any>(
+  options: ArrayPagerOptions<T, F>
+): PagedData<T> {
+  const CACHE_KEY = `${options.collectionName}_array_pager_state_`; //
+  const store = new ReactiveDataStore({})
+
+  // Baseline backing arrays managed by this adapter instance
+  let pristineData = [...(options.initialData ?? [])];
+  let activeScope: 'page' | 'collection' = 'collection';
+  let remoteTotalRecords: number | undefined = undefined;
+
+  // Track active filter parameters
+  let currentPageNum = options.page ?? 1;
+  let currentPageSize = options.size ?? 20; // Defaulting to 20 per your page controller sentinel
+  let currentSort: SortConfiguration<T>[] = [];
+  let currentFilter: QueryFilter<T> | undefined = undefined;
+
+  // Tracker for errors across async horizons
+  let operationalError: any = undefined;
+
+  const { match } = createMatcher<T, F>(options.customFunctions ?? {}); //
+  const { sort: localSort} = createSorter()
+  const selector = store.select((s: any) => s[CACHE_KEY]); //
+
+  // Default fallback layout conforming strictly to Page<T>
+  const sentinel: Page<T> = { //
+    data: [], //
+    loading: true, //
+    error: undefined,
+    page: { //
+      number: 1, //
+      size: currentPageSize, //
+      count: 0, //
+      total: 0, //
+      pages: 1, //
+    },
+  };
+
+  /**
+   * Constructs the current active QueryDSL footprint.
+   */
+  const buildQueryDSL = (): QueryDSL<T, F> => ({ //
+    filters: currentFilter, //
+    sort: currentSort, //
+    pagination: { //
+      type: 'offset', //
+      offset: (currentPageNum - 1) * currentPageSize, //
+      limit: currentPageSize //
+    }
+  });
+
+  /**
+   * Orchestrates the fetching lifecycle and syncs results into the centralized store.
+   */
+  const executeDataPipeline = async (isLoadingFallback = true) => {
+    if (options.fetch) {
+      operationalError = undefined;
+
+      if (isLoadingFallback) {
+        // Broadcast transitional loading state via the central store
+        const previousState = selector.get() ?? sentinel;
+        await store.set({
+          [CACHE_KEY]: { ...previousState, loading: true, error: undefined }
+        });
+      }
+
+      try {
+        const queryDSL = buildQueryDSL();
+        const result = await options.fetch(queryDSL);
+
+        activeScope = result.scope;
+        remoteTotalRecords = result.total;
+
+        pristineData = result.replace
+          ? [...result.data]
+          : [...pristineData, ...result.data];
+      } catch (error) {
+        operationalError = error;
+      }
+    }
+
+    // Process and dispatch to store
+    const updatedPagePayload = computeProcessedPage(options.fetch ? isLoadingFallback : false);
+    await store.set({ [CACHE_KEY]: updatedPagePayload }); //
+  };
+
+  /**
+   * Coordinates local filtering, sorting and slicing transformations
+   * based on the active structural scope strategy.
+   */
+  const computeProcessedPage = (isLoadingFlag: boolean): Page<T> => { //
+    let records = [...pristineData];
+
+    if (activeScope === 'collection') {
+      // Execute standard local processing passes over the full source collection
+      if (currentFilter) {
+        records = records.filter((item) => match(item, currentFilter!)); //
+      }
+      if (currentSort.length > 0) {
+        records = localSort(records, currentSort); //
+      }
+
+      const total = records.length;
+      const pages = Math.ceil(total / currentPageSize) || 1;
+
+      if (currentPageNum > pages) currentPageNum = pages;
+      if (currentPageNum < 1) currentPageNum = 1;
+
+      const startIdx = (currentPageNum - 1) * currentPageSize;
+      const slicedData = records.slice(startIdx, startIdx + currentPageSize);
+
+      return {
+        data: slicedData as any,
+        loading: isLoadingFlag,
+        error: operationalError,
+        page: { //
+          number: currentPageNum,
+          size: currentPageSize,
+          count: slicedData.length,
+          total,
+          pages,
+        }
+      };
+    }
+
+    // Server-Driven mode: Data array has already been shaped for this target viewport
+    const total = remoteTotalRecords ?? records.length;
+    const pages = Math.ceil(total / currentPageSize) || 1;
+
+    return {
+      data: records as any,
+      loading: isLoadingFlag,
+      error: operationalError,
+      page: { //
+        number: currentPageNum,
+        size: currentPageSize,
+        count: records.length,
+        total,
+        pages,
+      }
+    };
+  };
+
+  // Kickstart immediate bootstrapping pass
+  executeDataPipeline(true);
+
+  return {
+    page: () => selector.get() ?? sentinel, //
+
+    navigate: async (page: number) => {
+      if (page < 1) throw new Error("Page number must be >= 1"); //
+      currentPageNum = page;
+      await executeDataPipeline(true);
+    },
+
+    resize: async (size: number, page: number) => {
+      if (size < 1) throw new Error("Page size must be >= 1"); //
+      currentPageSize = size;
+      currentPageNum = page;
+      await executeDataPipeline(true);
+    },
+
+    sort: async (sortConfig) => {
+      currentSort = Array.isArray(sortConfig) ? sortConfig : [sortConfig];
+      currentPageNum = 1; // Reset window index
+      await executeDataPipeline(true);
+    },
+
+    filter: async (queryFilter) => {
+      currentFilter = queryFilter;
+      currentPageNum = 1; // Reset window index
+      await executeDataPipeline(true);
+    },
+
+    refresh: async (delay: number = 600) => { //
+      const previousState = selector.get() ?? sentinel;
+      await store.set({
+        [CACHE_KEY]: { ...previousState, loading: true } //
+      });
+
+      await Promise.all([
+        new Promise((resolve) => setTimeout(resolve, delay)), //
+        executeDataPipeline(false) // Handle full resolution pipeline passing down false to bypass flashing double mutations
+      ]);
+
+      const finishedState = selector.get() ?? sentinel;
+      await store.set({
+        [CACHE_KEY]: { ...finishedState, loading: false } //
+      });
+    },
+
+    subscribe: (listener) => {
+      return selector.subscribe((state) => { //
+        listener(state); //
+      });
+    },
+
+    invalidate: async () => {
+      await store.set({ [CACHE_KEY]: DELETE_SYMBOL }); //
+      pristineData = [];
+    },
+  };
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+  test: {
+    globalSetup: ["./test-setup.ts"],
+    fileParallelism: false,
+  },
+})