@asaidimu/hestia 1.0.0 → 1.0.1

package/auth/store.ts

@@ -1,4 +1,4 @@
-import { HestiaNetworkClient, IdentityProvider } from "../core/client";
+import { HestiaNetworkClient, type IdentityProvider } from "../core/client";
 import type { LoginResult, ServerHealth, TokenPair } from "./types";
 
 export class HestiaAuth {
@@ -29,7 +29,7 @@ export class HestiaAuth {
     name: string,
   ): Promise<{ _id_: string; email: string; name: string }> {
     const res = await this.client.post<{
-      data: { _id_: string; email: string; name: string, scopes:string };
+      data: { _id_: string; email: string; name: string, permissions: string[] };
     }>("/system/auth/user", { email, password, name });
     return res.data!.data;
   }

package/auth/types.ts

@@ -1,4 +1,4 @@
-import { UserIdentity } from "../system/identity/types"
+import type { UserIdentity } from "../system/identity/types"
 
 export interface TokenPair {
   access: string

package/blobs/store.ts

@@ -2,7 +2,8 @@ import type { QueryDSL } from "@asaidimu/query";
 import { ReactiveDataStore } from "@asaidimu/utils-store";
 import { HestiaNetworkClient } from "../core/client";
 import { createPagedController } from "../core/pager";
-import type { Page, PagedData } from "../core/types";
+import type { Document, Page, PagedData, StoreEvent } from "../core/types";
+import type { DocumentStore } from "../core/types";
 import type {
     BlobDocument,
     BlobMeta,
@@ -34,12 +35,7 @@ function pageMeta<T extends Record<string,any>>(items: T[]): Page<T>["page"] {
   };
 }
 
-/**
- * Namespace-scoped blob facade shaped like HestiaCollection.
- * Wraps blob CRUD behind a DocumentStore-compatible interface
- * so you can use DataTable + PagedData.
- */
-export class BlobNamespace {
+export class BlobNamespace implements DocumentStore<BlobMeta, QueryDSL<BlobMeta>, string, QueryDSL<BlobMeta>, Record<string, unknown>, string, Record<string, any>, Record<string, unknown>, { key: string; contentType?: string }, Record<string, unknown>> {
   private pagerOptions = {};
   private pager: PagedData<BlobMeta>;
   private prefixFilter = "";
@@ -85,7 +81,7 @@ export class BlobNamespace {
     return { data: items.map(asDoc), loading: false, page: pageMeta(items), error: undefined };
   }
 
-  async head(key: string): Promise<BlobDocument | undefined> {
+  async read(key: string): Promise<Document<BlobMeta> | undefined> {
     try {
       const res = await this.client.get<{ data: BlobMeta }>(
         `${this.basePath()}/${encodeURIComponent(key)}`,
@@ -104,76 +100,83 @@ export class BlobNamespace {
     }
   }
 
-  async upload(
-    key: string,
-    data: Blob,
-    contentType?: string,
-  ): Promise<BlobDocument> {
-    const headers: Record<string, string> = {};
-    const ct = contentType || data.type;
-    if (ct) headers["Content-Type"] = ct;
+  async create(_props: { data: Partial<BlobMeta> }): Promise<Document<BlobMeta> | undefined> {
+    throw new Error("Use upload() to create blobs");
+  }
 
-    const res = await this.client.post<{ data: BlobMeta }>(
+  async update(props: { data: Partial<BlobMeta>; options?: Record<string, any> }): Promise<Document<BlobMeta> | undefined> {
+    const key = props.options?.key as string;
+    if (!key) throw new Error("options.key is required for blob update");
+    const res = await this.client.patch<{ data: BlobMeta }>(
       `${this.basePath()}/${encodeURIComponent(key)}`,
-      data,
-      { headers, bodyType: "blob" },
+      { custom: props.data },
     );
     return asDoc(res.data!.data);
   }
 
-  async download(
-    key: string,
-  ): Promise<{ data: Blob; contentType: string }> {
-    const res = await this.client.get<Blob>(
+  async delete(key: string): Promise<void> {
+    await this.client.delete(
       `${this.basePath()}/${encodeURIComponent(key)}`,
-      { responseType: "blob" },
     );
-    const blob = res.data!;
-    return { data: blob, contentType: blob.type };
   }
 
-  async updateMetadata(key: string, custom: Record<string, any>): Promise<BlobMeta> {
-    const res = await this.client.patch<{ data: BlobMeta }>(
-      `${this.basePath()}/${encodeURIComponent(key)}`,
-      { custom },
-    );
-    return res.data!.data;
+  async list(options?: QueryDSL<BlobMeta>): Promise<Page<BlobMeta>> {
+    return this.find(options ?? {});
   }
 
-  async delete(key: string): Promise<void> {
-    await this.client.delete(
+  async upload(props: { file: File; options?: { key?: string; contentType?: string } }): Promise<Document<BlobMeta> | undefined> {
+    const key = (props.options as any)?.key as string;
+    if (!key) throw new Error("options.key is required for blob upload");
+    const headers: Record<string, string> = {};
+    const ct = props.options?.contentType || props.file.type;
+    if (ct) headers["Content-Type"] = ct;
+
+    const res = await this.client.post<{ data: BlobMeta }>(
       `${this.basePath()}/${encodeURIComponent(key)}`,
+      props.file,
+      { headers, bodyType: "blob" },
     );
+    return asDoc(res.data!.data);
   }
 
-  async list(): Promise<BlobMeta[]> {
-    const res = await this.client.post<{
-      data: { blobs: BlobMeta[] };
-    }>(`${this.basePath()}/query`, {});
-    return res.data?.data?.blobs ?? [];
+  async subscribe(_scope: string, _callback: (event: StoreEvent) => void): Promise<() => void> {
+    throw new Error("Subscription not supported for blobs");
   }
 
-  page(): PagedData<BlobMeta> {
+  async notify(_event: StoreEvent): Promise<void> {
+    throw new Error("Notify not supported for blobs");
+  }
+
+  stream(_options: Record<string, unknown>, _onStreamChange: () => void): {
+    stream: () => AsyncIterable<Document<BlobMeta>>;
+    cancel: () => void;
+    status: () => "active" | "cancelled" | "completed";
+  } {
+    throw new Error("Stream not supported for blobs");
+  }
+
+  page(_options?: Record<string, unknown>): PagedData<BlobMeta> {
     return this.pager;
   }
+
+  async download(key: string): Promise<{ data: Blob; contentType: string }> {
+    const res = await this.client.get<Blob>(
+      `${this.basePath()}/${encodeURIComponent(key)}`,
+      { responseType: "blob" },
+    );
+    const blob = res.data!;
+    return { data: blob, contentType: blob.type };
+  }
 }
 
-/**
- * Top-level blob client. Entry point for all blob operations.
- *
- * Usage:
- *   client.blobs.listNamespaces()
- *   const ns = client.blobs.namespace("my-bucket")
- *   ns.find({ prefix: "images/" })
- *   ns.upload("logo.png", file)
- *   const { data } = await ns.download("logo.png")
- */
 export class HestiaBlobClient {
-  constructor(private client: HestiaNetworkClient) {}
+  private apiPrefix: string;
 
-  private nsBase = "/system/blobs";
+  constructor(private client: HestiaNetworkClient, apiPrefix: string = "/api") {
+    this.apiPrefix = apiPrefix;
+  }
 
-  // ── Namespace operations ──────────────────────────────────────────────
+  private nsBase = "/system/blobs";
 
   async namespaces(): Promise<NamespaceInfo[]> {
     const res = await this.client.post<{
@@ -196,13 +199,11 @@ export class HestiaBlobClient {
     );
   }
 
-
   blob(namespace: string, key:string) {
-      return `${this.client.base()}${this.nsBase}/blob/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`
+      return `${this.client.base()}${this.apiPrefix}${this.nsBase}/blob/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`
   }
-  // ── Namespace-scoped facade ───────────────────────────────────────────
 
   namespace(ns: string): BlobNamespace {
     return new BlobNamespace(this.client, ns);
   }
-}
+}

package/collections/store.ts

@@ -1,59 +1,88 @@
 import { HestiaNetworkClient } from "../core/client"
 import { HestiaCollection } from "../core/collection"
-import type { Document } from "../core/types"
+import type { Document, Page, PagedData, StoreEvent } from "../core/types"
+import type { DocumentStore } from "../core/types"
 import type { CollectionMeta } from "./types"
 
-export class HestiaCollections {
+export class HestiaCollections implements DocumentStore<CollectionMeta, Record<string, unknown>, string, Record<string, unknown>, Record<string, unknown>, string, string, Record<string, unknown>> {
   constructor(private client: HestiaNetworkClient) {}
 
-  async list(): Promise<{ collections: CollectionMeta[]; total: number }> {
+  async find(_query?: Record<string, unknown>): Promise<Page<CollectionMeta>> {
     const res = await this.client.get<{
       data: { name: string; schema: any; created: string; updated: string }[]
     }>("/system/collections/collection")
     const items = res.data?.data ?? []
+    const docs: Document<CollectionMeta>[] = items.map((i) => ({
+      _id_: i.name,
+      _metadata_: { checksum: "", created: i.created, updated: i.updated, version: 1 },
+      name: i.name,
+      schema: i.schema,
+      created: i.created,
+      updated: i.updated,
+    }))
     return {
-      collections: items.map((i) => ({
-        name: i.name,
-        schema: i.schema,
-        created: i.created,
-        updated: i.updated,
-      })),
-      total: items.length,
+      data: docs,
+      loading: false,
+      page: { number: 1, size: docs.length, count: docs.length, total: docs.length, pages: 1 },
     }
   }
 
-  async read(name: string): Promise<CollectionMeta | undefined> {
+  async read(name: string): Promise<Document<CollectionMeta> | undefined> {
     try {
       const res = await this.client.get<{ data: { name: string; schema: any; created: string; updated: string } }>(
         `/system/collections/collection/${encodeURIComponent(name)}`,
       )
       if (!res.data) return undefined
-      return res.data.data
+      const d = res.data.data
+      return { _id_: d.name, _metadata_: { checksum: "", created: d.created, updated: d.updated, version: 1 }, name: d.name, schema: d.schema, created: d.created, updated: d.updated }
     } catch (err: any) {
       if (err?.code === "SYNC-001-NF") return undefined
       throw err
     }
   }
 
-  async create(schema: any): Promise<Document<{ schema: any }>> {
-    const res = await this.client.post<{ data: Document<{ schema: any }> }>("/system/collections/collection", schema)
-    return res.data!.data
+  async create(props: { data: Partial<CollectionMeta> }): Promise<Document<CollectionMeta> | undefined> {
+    const res = await this.client.post<{ data: Document<{ schema: any }> }>("/system/collections/collection", props.data)
+    return res.data!.data as any as Document<CollectionMeta>
   }
 
-  async update(name: string, schema: any): Promise<Document<{ schema: any }>> {
-      throw new Error("Method not implemented")
-    // const res = await this.client.patch<{ data: Document<{ schema: any }> }>(
-    //   `/api/admin/collections/${encodeURIComponent(name)}`,
-    //   schema,
-    // )
-    // return res.data!.data
+  async update(_props: { data: Partial<CollectionMeta>; options?: string }): Promise<Document<CollectionMeta> | undefined> {
+    throw new Error("Collection update not implemented")
   }
 
   async delete(name: string): Promise<void> {
     await this.client.delete(`/system/collections/collection/${encodeURIComponent(name)}`)
   }
 
+  async list(_options?: Record<string, unknown>): Promise<Page<CollectionMeta>> {
+    return this.find()
+  }
+
+  async upload(_props: { file: File }): Promise<Document<CollectionMeta> | undefined> {
+    throw new Error("Upload not supported for collections")
+  }
+
+  async subscribe(_scope: string, _callback: (event: StoreEvent) => void): Promise<() => void> {
+    throw new Error("Subscription not supported for collections")
+  }
+
+  async notify(_event: StoreEvent): Promise<void> {
+    throw new Error("Notify not supported for collections")
+  }
+
+  stream(_options: Record<string, unknown>, _onStreamChange: () => void): {
+    stream: () => AsyncIterable<Document<CollectionMeta>>;
+    cancel: () => void;
+    status: () => "active" | "cancelled" | "completed";
+  } {
+    throw new Error("Stream not supported for collections")
+  }
+
+  page(_options?: Record<string, unknown>): PagedData<CollectionMeta> {
+    throw new Error("Pagination not supported for collection metadata; use documents(name)")
+  }
+
   documents<T extends Record<string, any>>(collectionName: string): HestiaCollection<T> {
-    return new HestiaCollection<T>(this.client,collectionName)
+    return new HestiaCollection<T>(this.client, collectionName)
   }
-}
+}

package/collections/types.ts

@@ -1,4 +1,4 @@
-import { SchemaDefinition } from "@asaidimu/utils-schema"
+import type { SchemaDefinition } from "@asaidimu/utils-schema"
 import type { Document } from "../core/types"
 
 export interface CollectionMeta {

package/container.ts

@@ -1,4 +1,3 @@
-import { ArtifactContainer } from "@asaidimu/utils-artifacts";
 import type { SimplePersistence } from "@asaidimu/utils-persistence";
 import { ReactiveDataStore } from "@asaidimu/utils-store";
 import { HestiaAuth } from "./auth/store";
@@ -9,7 +8,7 @@ import {
 } from "./core/client";
 import { HestiaKeyStore } from "./system/api-keys/store";
 import { HestiaUsers } from "./system/identity/store";
-import { UserIdentity } from "./system/identity/types";
+import type { UserIdentity } from "./system/identity/types";
 import { HestiaLogs } from "./system/logs/store";
 import { HestiaPolicies } from "./system/policies/store";
 import { HestiaBlobClient } from "./blobs/store";
@@ -17,6 +16,7 @@ import { HestiaCapabilities } from "./system/capabilities/store";
 
 export interface HestiaConfig {
   baseUrl: string;
+  apiPrefix?: string;
   persistence?: SimplePersistence<AuthState>;
 }
 
@@ -26,11 +26,8 @@ interface AuthState {
   identity: UserIdentity | null;
 }
 
-type Registry = Record<string, any>;
-
 export class HestiaClient {
   readonly store: ReactiveDataStore<AuthState>;
-  readonly container: ArtifactContainer<Registry, any>;
   readonly client: HestiaNetworkClient;
   readonly auth: HestiaAuth;
   readonly users: HestiaUsers;
@@ -50,8 +47,6 @@ export class HestiaClient {
       config.persistence,
     );
 
-    this.container = new ArtifactContainer<Registry, any>(this.store);
-
     const tokenProvider: IdentityProvider = {
       identity: () => this.store.get().identity,
       token: (key: "access" | "refresh") => this.store.get()[key],
@@ -63,8 +58,10 @@ export class HestiaClient {
         void (await this.store.set({ access: null, refresh: null })),
     };
 
+    const apiPrefix = config.apiPrefix ?? "/api";
+
     this.tokenProvider = tokenProvider;
-    this.client = new HestiaNetworkClient(config.baseUrl, tokenProvider, () =>
+    this.client = new HestiaNetworkClient(config.baseUrl, apiPrefix, tokenProvider, () =>
       this.onAuthStateChanged?.(),
     );
 
@@ -75,9 +72,10 @@ export class HestiaClient {
     this.logs = new HestiaLogs(
       this.client,
       config.baseUrl,
+      apiPrefix,
     );
     this.collections = new HestiaCollections(this.client);
-    this.blobs = new HestiaBlobClient(this.client);
+    this.blobs = new HestiaBlobClient(this.client, apiPrefix);
     this.capabilities = new HestiaCapabilities(this.client)
   }
 

package/core/client.ts

@@ -5,7 +5,7 @@ import {
 } from "@asaidimu/network-client";
 import { SystemError } from "@asaidimu/utils-error";
 import { parseErrorBody, toSystemError } from "./errors";
-import { UserIdentity } from "../system/identity/types";
+import type { UserIdentity } from "../system/identity/types";
 
 export interface IdentityProvider {
   identity(): UserIdentity | null;
@@ -39,6 +39,22 @@ interface RequestOptions {
   signal?: AbortSignal;
 }
 
+// Handlers driving a live server-sent-events stream opened via
+// HestiaNetworkClient.openStream(). onMessage fires once per parsed SSE
+// "data:" payload (still a raw string — callers decide whether/how to
+// JSON.parse it); onOpen/onClose/onError report connection lifecycle.
+export interface StreamHandlers {
+  onMessage: (data: string) => void;
+  onError?: (err: Error) => void;
+  onOpen?: () => void;
+  onClose?: () => void;
+}
+
+export interface StreamOptions {
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
 export class HestiaNetworkClient {
   private raw: NetworkClient;
   private refreshing: Promise<void> | null = null;
@@ -46,6 +62,7 @@ export class HestiaNetworkClient {
 
   constructor(
     private baseUrl: string,
+    private apiPrefix: string,
     private tokens: IdentityProvider,
     private onAuthStateChanged?: () => void,
   ) {
@@ -70,12 +87,39 @@ export class HestiaNetworkClient {
   base() {
     return this.baseUrl;
   }
+
+  prefix(): string {
+    return this.apiPrefix;
+  }
+
+  // Single entry-point for all path manipulation (prefix handling).
+  // Returns the relative path that should be appended to the base URL.
+  private canonicalPath(path: string): string {
+    // 1. Strip any leading slashes so we work with a clean base (e.g., "api/api/system" or "/api/system")
+    let cleanPath = path.replace(/^\/+/, "");
+
+    if (this.apiPrefix) {
+      // 2. Strip leading slashes from the prefix too, just to be safe and consistent
+      const cleanPrefix = this.apiPrefix.replace(/^\/+/, "");
+
+      // 3. If the path already starts with the prefix followed by a slash (or is exactly the prefix),
+      // remove it so we don't double up.
+      const prefixRegex = new RegExp(`^${cleanPrefix}/?`);
+      cleanPath = cleanPath.replace(prefixRegex, "");
+
+      // 4. Combine them cleanly
+      return `${cleanPrefix}/${cleanPath}`;
+    }
+
+    return cleanPath;
+  }
+
   async storeTokens(access: string, refresh?: string): Promise<void> {
     this.refreshFailed = false;
     await this.tokens.setTokens(access, refresh ?? "");
   }
 
-  private   async refreshToken(): Promise<void> {
+  private async refreshToken(): Promise<void> {
     if (this.refreshing) return this.refreshing;
 
     this.refreshing = this.doRefresh();
@@ -92,7 +136,7 @@ export class HestiaNetworkClient {
     const body = refresh ? { refresh_token: refresh } : {};
     const res = await this.raw.patch<{
       data: { token: { access: string; refresh: string } };
-    }>("/system/auth/session", body);
+    }>(this.canonicalPath("/system/auth/session"), body);
 
     if (!res.success || !res.data) {
       this.tokens.clear();
@@ -114,6 +158,8 @@ export class HestiaNetworkClient {
     body?: unknown,
     options?: RequestOptions,
   ): Promise<HestiaResponse<T>> {
+    const fullPath = this.canonicalPath(path);
+
     const opts: any = {};
     if (options?.headers) opts.headers = options.headers;
     if (options?.responseType) opts.responseType = options.responseType;
@@ -123,13 +169,13 @@ export class HestiaNetworkClient {
     let res: ApiResponse<T>;
 
     if (method === "GET") {
-      res = await this.raw.get<T>(path, opts);
+      res = await this.raw.get<T>(fullPath, opts);
     } else {
       const bodyOpts = options?.bodyType
         ? { type: options.bodyType as BodyType }
         : undefined;
       res = (await (this.raw as any)[method.toLowerCase()](
-        path,
+        fullPath,
         body,
         opts,
         bodyOpts,
@@ -153,7 +199,7 @@ export class HestiaNetworkClient {
         });
       }
 
-      // If a previous refresh already failed, don't loop — the tokens
+      // If a previous refresh already failed, don’t loop — the tokens
       // (including any cookie fallback) are known to be dead.
       if (this.refreshFailed) {
         this.tokens.clear();
@@ -180,17 +226,20 @@ export class HestiaNetworkClient {
       const newAccess = this.tokens.token("access");
       const retryOpts: any = { ...opts };
       if (newAccess) {
-        retryOpts.headers = { ...(opts.headers ?? {}), Authorization: `Bearer ${newAccess}` };
+        retryOpts.headers = {
+          ...(opts.headers ?? {}),
+          Authorization: `Bearer ${newAccess}`,
+        };
       }
 
       if (method === "GET") {
-        res = await this.raw.get<T>(path, retryOpts);
+        res = await this.raw.get<T>(fullPath, retryOpts);
       } else {
         const bodyOpts = options?.bodyType
           ? { type: options.bodyType as BodyType }
           : undefined;
         res = (await (this.raw as any)[method.toLowerCase()](
-          path,
+          fullPath,
           body,
           retryOpts,
           bodyOpts,
@@ -244,4 +293,116 @@ export class HestiaNetworkClient {
   ): Promise<HestiaResponse<T>> {
     return this.request<T>("DELETE", path, body, options);
   }
+
+  // Opens an authenticated, long-lived GET request against a
+  // "text/event-stream" endpoint (e.g. system:audit:log:stream) and parses
+  // standard SSE framing ("data: ...\n\n") off the raw response body.
+  //
+  // Bypasses `raw` deliberately: the wrapped network-client's request/
+  // response cycle is built around single JSON responses, not an
+  // indefinitely-open ReadableStream, so this talks to `fetch` directly.
+  // On a 401 it will attempt exactly one token refresh and reconnect once
+  // before giving up — mirroring `request()`'s retry behavior, but capped
+  // at a single attempt since a stream that keeps failing auth shouldn’t
+  // loop indefinitely in the background.
+  async openStream(
+    path: string,
+    handlers: StreamHandlers,
+    options?: StreamOptions,
+  ): Promise<void> {
+    const attempt = async (isRetry: boolean): Promise<void> => {
+      const access = this.tokens.token("access");
+      const isApiKeyAuth = !!options?.headers?.["X-API-Key"];
+      const headers: Record<string, string> = {
+        Accept: "text/event-stream",
+        ...(access && !isApiKeyAuth
+          ? { Authorization: `Bearer ${access}` }
+          : {}),
+        ...(options?.headers ?? {}),
+      };
+
+      const url = `${this.baseUrl.replace(/\/+$/, "")}/${this.canonicalPath(path)}`;
+
+      let response: Response;
+      try {
+        response = await fetch(url, {
+          method: "GET",
+          headers,
+          signal: options?.signal,
+        });
+      } catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+          handlers.onClose?.();
+          return;
+        }
+        handlers.onError?.(err instanceof Error ? err : new Error(String(err)));
+        return;
+      }
+
+      if (response.status === 401 && !isRetry && !isApiKeyAuth) {
+        try {
+          await this.refreshToken();
+        } catch {
+          this.tokens.clear();
+          this.onAuthStateChanged?.();
+          handlers.onError?.(
+            new SystemError({
+              code: "AUTH-002-UNAUTH",
+              message: "Session expired",
+            }),
+          );
+          return;
+        }
+        return attempt(true);
+      }
+
+      if (!response.ok || !response.body) {
+        handlers.onError?.(
+          new Error(`Stream request failed with status ${response.status}`),
+        );
+        return;
+      }
+
+      handlers.onOpen?.();
+
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+
+          let separatorIndex = buffer.indexOf("\n\n");
+          while (separatorIndex !== -1) {
+            const rawEvent = buffer.slice(0, separatorIndex);
+            buffer = buffer.slice(separatorIndex + 2);
+
+            const dataLines = rawEvent
+              .split("\n")
+              .filter((line) => line.startsWith("data:"))
+              .map((line) => line.slice(5).trim());
+
+            if (dataLines.length > 0) {
+              handlers.onMessage(dataLines.join("\n"));
+            }
+
+            separatorIndex = buffer.indexOf("\n\n");
+          }
+        }
+      } catch (err) {
+        if (!(err instanceof Error && err.name === "AbortError")) {
+          handlers.onError?.(
+            err instanceof Error ? err : new Error(String(err)),
+          );
+        }
+      } finally {
+        handlers.onClose?.();
+      }
+    };
+
+    return attempt(false);
+  }
 }