@asaidimu/hestia 1.0.0

package/README.md

@@ -0,0 +1,139 @@
+# @asaidimu/hestia
+
+TypeScript client SDK for the [Hestia](https://github.com/asaidimu/hestia) platform — a lightweight, modular backend framework.
+
+## Features
+
+- **Auth** — login, register, refresh, logout, session management with auto-refresh on 401
+- **Collections** — generic CRUD over any named collection via `HestiaCollection<T>`
+- **API Keys** — create, list, get, update, rotate, delete API keys
+- **Policies** — manage policy operations, rules, validation, and reload
+- **Audit Logs** — query and filter audit entries
+- **Blobs** — upload, download, list, and manage blob storage namespaces
+- **Capabilities** — query available capabilities
+- **Reactive Paging** — observable paginated data with resize/navigate/subscribe
+
+## Installation
+
+```bash
+npm install @asaidimu/hestia
+# or
+bun add @asaidimu/hestia
+```
+
+## Quick Start
+
+```ts
+import { HestiaClient } from "@asaidimu/hestia"
+
+const api = new HestiaClient({ baseUrl: "http://localhost:8070" })
+
+// Login as admin
+const { token, user } = await api.auth.login("admin@test.local", "password123")
+console.log("Logged in as", user.email)
+
+// List users
+const { data: users } = await api.users.find()
+console.log(`Found ${users.length} users`)
+
+// Create an API key
+const key = await api.keys.create({ name: "CI/CD Deploy Key" })
+console.log("API key:", key.key)
+
+// Reactive pager
+const pager = api.users.page()
+pager.subscribe((page) => console.log("Page:", page.page.number))
+await pager.resize(25, 1)
+```
+
+## API
+
+### `HestiaClient`
+
+The main entry point. Construct with a `baseUrl` pointing to a Hestia server.
+
+| Property | Type | Description |
+|---|---|---|
+| `auth` | `HestiaAuth` | Authentication (login, register, refresh, logout) |
+| `users` | `HestiaUsers` | User management |
+| `keys` | `HestiaKeyStore` | API key management |
+| `policies` | `HestiaPolicies` | Policy operations and rules |
+| `logs` | `HestiaLogs` | Audit log queries |
+| `collections` | `HestiaCollections` | Generic collection metadata |
+| `blobs` | `HestiaBlobClient` | Blob (file) storage |
+| `capabilities` | `HestiaCapabilities` | Available capabilities |
+| `client` | `HestiaNetworkClient` | Low-level HTTP client |
+
+### Auth
+
+```ts
+// Login — stores tokens and identity in the reactive store
+const result = await api.auth.login(email, password)
+
+// Register a new user (requires admin session)
+const user = await api.auth.register(email, password, name)
+
+// Refresh tokens
+const pair = await api.auth.refresh(refreshToken)
+
+// Logout — clears stored tokens
+await api.auth.logout()
+
+// Health check (public endpoint, no auth required)
+const health = await api.auth.health()
+```
+
+### Collections
+
+```ts
+// Get a typed collection handle
+const docs = api.collection<MyType>("my_collection")
+
+// CRUD operations
+const list = await docs.find(query?)
+const item = await docs.read(id)
+const created = await docs.create(document)
+const updated = await docs.update(id, partial)
+await docs.delete(id)
+```
+
+### Reactive Paging
+
+```ts
+const pager = api.users.page()
+
+// Subscribe to page changes
+const unsub = pager.subscribe((page) => render(page.data))
+
+// Navigate, resize, sort, filter
+await pager.navigate(2)
+await pager.resize(50, 1)
+await pager.sort({ field: "email", order: "asc" })
+await pager.filter({ email: { $like: "%@example.com" } })
+
+// Manual refresh
+await pager.refresh()
+
+// Cleanup
+unsub()
+```
+
+### Auto-Refresh
+
+The client transparently refreshes expired JWT access tokens on 401 responses. Concurrent requests that receive 401 are deduplicated — only one refresh call is made. API-key requests (with `X-API-Key` header) are excluded from auto-refresh.
+
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests (requires a running test-server on :8070)
+./test-server &
+bun test
+```
+
+## License
+
+MIT

package/auth/store.ts

@@ -0,0 +1,75 @@
+import { HestiaNetworkClient, IdentityProvider } from "../core/client";
+import type { LoginResult, ServerHealth, TokenPair } from "./types";
+
+export class HestiaAuth {
+  constructor(
+    private client: HestiaNetworkClient,
+    private provider: IdentityProvider,
+  ) {}
+
+  async health(): Promise<ServerHealth> {
+    const res = await this.client.get<{ data: ServerHealth }>("/system/core/health");
+    return res.data!.data;
+  }
+
+  async login(email: string, password: string): Promise<LoginResult> {
+    const res = await this.client.post<{ data: LoginResult }>(
+      "/system/auth/session",
+      { email, password },
+    );
+    const result = res.data!.data;
+    this.provider.setIdentity(result.user);
+    this.client.storeTokens(result.token.access, result.token.refresh);
+    return result;
+  }
+
+  async register(
+    email: string,
+    password: string,
+    name: string,
+  ): Promise<{ _id_: string; email: string; name: string }> {
+    const res = await this.client.post<{
+      data: { _id_: string; email: string; name: string, scopes:string };
+    }>("/system/auth/user", { email, password, name });
+    return res.data!.data;
+  }
+
+  async refresh(refreshToken?: string): Promise<TokenPair> {
+    const body = refreshToken ? { refresh_token: refreshToken } : {};
+    const res = await this.client.patch<{ data: { token: TokenPair } }>(
+      "/system/auth/session",
+      body,
+    );
+    return res.data!.data.token;
+  }
+
+  async logout(): Promise<void> {
+    const refresh = this.provider.token("refresh");
+    const body = refresh ? { refresh_token: refresh } : {};
+    await this.client.delete("/system/auth/session", body);
+    await this.provider.clear();
+  }
+
+  async requestPasswordReset(email: string): Promise<void> {
+    await this.client.post("/system/auth/password", { email });
+  }
+
+  async confirmPasswordReset(
+    resetToken: string,
+    password: string,
+  ): Promise<void> {
+    await this.client.patch(
+      "/system/auth/password",
+      { password, token:resetToken },
+      { headers: { Authorization: `Bearer ${resetToken}` } },
+    );
+  }
+
+  async bootstrap(key: string, password: string, email: string): Promise<void> {
+    await this.client.patch(
+      "/system/auth/bootstrap",
+      { password, email },
+      { headers: { "X-API-Key": key } },
+    );
+  }
+}

package/auth/types.ts

@@ -0,0 +1,38 @@
+import { UserIdentity } from "../system/identity/types"
+
+export interface TokenPair {
+  access: string
+  refresh: string
+  type: string
+  validity: number
+}
+
+export interface LoginResult {
+  token: TokenPair
+  user: UserIdentity
+}
+
+export interface ServerHealth {
+  bootstrapped: boolean
+  ok: boolean
+}
+
+export interface LoginRequest {
+  email: string
+  password: string
+}
+
+export interface RegisterRequest {
+  email: string
+  password: string
+  name: string
+}
+
+export interface RefreshRequest {
+  refresh_token: string
+}
+
+export interface BootstrapPasswordRequest {
+  password: string
+  email: string
+}

package/blobs/store.ts

@@ -0,0 +1,208 @@
+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 {
+    BlobDocument,
+    BlobMeta,
+    CreateNamespaceRequest,
+    ListBlobsRequest,
+    NamespaceInfo,
+} from "./types";
+
+function asDoc(b: BlobMeta): BlobDocument {
+  return {
+    _id_: b.key,
+    _metadata_: {
+      checksum: "",
+      created: b.created_at,
+      updated: b.updated_at ?? b.created_at,
+      version: 1,
+    },
+    ...b,
+  };
+}
+
+function pageMeta<T extends Record<string,any>>(items: T[]): Page<T>["page"] {
+  return {
+    number: 1,
+    size: items.length,
+    count: items.length,
+    total: items.length,
+    pages: 1,
+  };
+}
+
+/**
+ * Namespace-scoped blob facade shaped like HestiaCollection.
+ * Wraps blob CRUD behind a DocumentStore-compatible interface
+ * so you can use DataTable + PagedData.
+ */
+export class BlobNamespace {
+  private pagerOptions = {};
+  private pager: PagedData<BlobMeta>;
+  private prefixFilter = "";
+
+  constructor(
+    private client: HestiaNetworkClient,
+    private ns: string,
+  ) {
+    this.pager = createPagedController<BlobMeta>(
+      `blobs_${ns}`,
+      new ReactiveDataStore<any>({}),
+      this.pagerOptions,
+      (query) => this.find(query),
+    );
+  }
+
+  name() {
+    return this.ns;
+  }
+
+  setPrefix(prefix: string) {
+    this.prefixFilter = prefix;
+  }
+
+  private basePath() {
+    return `/system/blobs/blob/${encodeURIComponent(this.ns)}`;
+  }
+
+  async find(query?: QueryDSL<BlobMeta>): Promise<Page<BlobMeta>> {
+    const prefix = this.prefixFilter || (query as any)?.prefix || "";
+    const limit =
+      (query as any)?.limit ?? query?.pagination?.limit ?? 0;
+
+    const req: ListBlobsRequest = {};
+    if (prefix) req.prefix = prefix;
+    if (limit) req.limit = limit;
+
+    const res = await this.client.post<{
+      data: { blobs: BlobMeta[] };
+    }>(`${this.basePath()}/query`, req);
+
+    const items = res.data?.data?.blobs ?? [];
+    return { data: items.map(asDoc), loading: false, page: pageMeta(items), error: undefined };
+  }
+
+  async head(key: string): Promise<BlobDocument | undefined> {
+    try {
+      const res = await this.client.get<{ data: BlobMeta }>(
+        `${this.basePath()}/${encodeURIComponent(key)}`,
+      );
+      if (!res.data?.data) return undefined;
+      return asDoc(res.data.data);
+    } catch (err: any) {
+      if (
+        err?.code === "SYNC-001-NF" ||
+        (err?.code === "INTERNAL_ERROR" &&
+          typeof err?.message === "string" &&
+          err.message.includes("not found"))
+      )
+        return undefined;
+      throw err;
+    }
+  }
+
+  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;
+
+    const res = await this.client.post<{ data: BlobMeta }>(
+      `${this.basePath()}/${encodeURIComponent(key)}`,
+      data,
+      { headers, bodyType: "blob" },
+    );
+    return asDoc(res.data!.data);
+  }
+
+  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 };
+  }
+
+  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 delete(key: string): Promise<void> {
+    await this.client.delete(
+      `${this.basePath()}/${encodeURIComponent(key)}`,
+    );
+  }
+
+  async list(): Promise<BlobMeta[]> {
+    const res = await this.client.post<{
+      data: { blobs: BlobMeta[] };
+    }>(`${this.basePath()}/query`, {});
+    return res.data?.data?.blobs ?? [];
+  }
+
+  page(): PagedData<BlobMeta> {
+    return this.pager;
+  }
+}
+
+/**
+ * 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 nsBase = "/system/blobs";
+
+  // ── Namespace operations ──────────────────────────────────────────────
+
+  async namespaces(): Promise<NamespaceInfo[]> {
+    const res = await this.client.post<{
+      data: { namespaces: NamespaceInfo[] };
+    }>(`${this.nsBase}/namespace/query`);
+    return res.data?.data?.namespaces ?? [];
+  }
+
+  async createNamespace(data: CreateNamespaceRequest): Promise<NamespaceInfo> {
+    const res = await this.client.post<{ data: NamespaceInfo }>(
+      `${this.nsBase}/namespace`,
+      data,
+    );
+    return res.data!.data;
+  }
+
+  async deleteNamespace(ns: string): Promise<void> {
+    await this.client.delete(
+      `${this.nsBase}/namespace/${encodeURIComponent(ns)}`,
+    );
+  }
+
+
+  blob(namespace: string, key:string) {
+      return `${this.client.base()}${this.nsBase}/blob/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`
+  }
+  // ── Namespace-scoped facade ───────────────────────────────────────────
+
+  namespace(ns: string): BlobNamespace {
+    return new BlobNamespace(this.client, ns);
+  }
+}

package/blobs/types.ts

@@ -0,0 +1,28 @@
+import type { Document } from "../core/types"
+
+export interface NamespaceInfo {
+  id: string
+  display_name: string
+}
+
+export interface BlobMeta {
+  key: string
+  namespace_id: string
+  content_type: string
+  size: number
+  created_at: string
+  updated_at?: string
+  custom?: Record<string, any>
+}
+
+export type BlobDocument = Document<BlobMeta>
+
+export interface ListBlobsRequest {
+  prefix?: string
+  limit?: number
+}
+
+export interface CreateNamespaceRequest {
+  display_name?: string
+  ns?: string
+}

package/collections/store.ts

@@ -0,0 +1,59 @@
+import { HestiaNetworkClient } from "../core/client"
+import { HestiaCollection } from "../core/collection"
+import type { Document } from "../core/types"
+import type { CollectionMeta } from "./types"
+
+export class HestiaCollections {
+  constructor(private client: HestiaNetworkClient) {}
+
+  async list(): Promise<{ collections: CollectionMeta[]; total: number }> {
+    const res = await this.client.get<{
+      data: { name: string; schema: any; created: string; updated: string }[]
+    }>("/system/collections/collection")
+    const items = res.data?.data ?? []
+    return {
+      collections: items.map((i) => ({
+        name: i.name,
+        schema: i.schema,
+        created: i.created,
+        updated: i.updated,
+      })),
+      total: items.length,
+    }
+  }
+
+  async read(name: string): Promise<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
+    } 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 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 delete(name: string): Promise<void> {
+    await this.client.delete(`/system/collections/collection/${encodeURIComponent(name)}`)
+  }
+
+  documents<T extends Record<string, any>>(collectionName: string): HestiaCollection<T> {
+    return new HestiaCollection<T>(this.client,collectionName)
+  }
+}

package/collections/types.ts

@@ -0,0 +1,11 @@
+import { SchemaDefinition } from "@asaidimu/utils-schema"
+import type { Document } from "../core/types"
+
+export interface CollectionMeta {
+  name: string
+  schema: SchemaDefinition
+  created: string
+  updated: string
+}
+
+export type CollectionDocument = Document<{ schema: any }>

package/container.ts

@@ -0,0 +1,95 @@
+import { ArtifactContainer } from "@asaidimu/utils-artifacts";
+import type { SimplePersistence } from "@asaidimu/utils-persistence";
+import { ReactiveDataStore } from "@asaidimu/utils-store";
+import { HestiaAuth } from "./auth/store";
+import { HestiaCollections } from "./collections/store";
+import {
+    HestiaNetworkClient,
+    type IdentityProvider,
+} from "./core/client";
+import { HestiaKeyStore } from "./system/api-keys/store";
+import { HestiaUsers } from "./system/identity/store";
+import { UserIdentity } from "./system/identity/types";
+import { HestiaLogs } from "./system/logs/store";
+import { HestiaPolicies } from "./system/policies/store";
+import { HestiaBlobClient } from "./blobs/store";
+import { HestiaCapabilities } from "./system/capabilities/store";
+
+export interface HestiaConfig {
+  baseUrl: string;
+  persistence?: SimplePersistence<AuthState>;
+}
+
+interface AuthState {
+  access: string | null;
+  refresh: string | null;
+  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;
+  readonly keys: HestiaKeyStore;
+  readonly policies: HestiaPolicies;
+  readonly logs: HestiaLogs;
+  readonly collections: HestiaCollections;
+  readonly blobs: HestiaBlobClient;
+  readonly capabilities: HestiaCapabilities
+  private tokenProvider: IdentityProvider;
+
+  private onAuthStateChanged?: () => void;
+
+  constructor(config: HestiaConfig) {
+    this.store = new ReactiveDataStore<AuthState>(
+      { access: null, refresh: null, identity: null },
+      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],
+      setTokens: async (access: string, refresh: string) =>
+        void (await this.store.set({ access, refresh })),
+      setIdentity: async (identity) =>
+        void (await this.store.set({ identity })),
+      clear: async () =>
+        void (await this.store.set({ access: null, refresh: null })),
+    };
+
+    this.tokenProvider = tokenProvider;
+    this.client = new HestiaNetworkClient(config.baseUrl, tokenProvider, () =>
+      this.onAuthStateChanged?.(),
+    );
+
+    this.auth = new HestiaAuth(this.client, tokenProvider);
+    this.users = new HestiaUsers(this.client);
+    this.keys = new HestiaKeyStore(this.client,);
+    this.policies = new HestiaPolicies(this.client);
+    this.logs = new HestiaLogs(
+      this.client,
+      config.baseUrl,
+    );
+    this.collections = new HestiaCollections(this.client);
+    this.blobs = new HestiaBlobClient(this.client);
+    this.capabilities = new HestiaCapabilities(this.client)
+  }
+
+  onAuthStateChange(callback: () => void) {
+    this.onAuthStateChanged = callback;
+  }
+
+  authenticated(): boolean {
+    return this.tokenProvider.token("access") !== null;
+  }
+
+  collection<T extends Record<string, any>>(name: string) {
+    return this.collections.documents<T>(name);
+  }
+}