@asaidimu/hestia 1.0.0

package/core/client.ts

@@ -0,0 +1,247 @@
+import {
+  createNetworkClient,
+  type NetworkClient,
+  type ApiResponse,
+} from "@asaidimu/network-client";
+import { SystemError } from "@asaidimu/utils-error";
+import { parseErrorBody, toSystemError } from "./errors";
+import { UserIdentity } from "../system/identity/types";
+
+export interface IdentityProvider {
+  identity(): UserIdentity | null;
+  token(key: "access" | "refresh"): string | null;
+  setTokens(access: string, refresh: string): Promise<void>;
+  setIdentity(id: UserIdentity | null): Promise<void>;
+  clear(): Promise<void>;
+}
+
+export class HestiaResponse<T> {
+  constructor(
+    public readonly data: T,
+    public readonly status: number,
+  ) {}
+}
+
+type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE" | "PUT";
+type BodyType = "json" | "form" | "text" | "blob" | "stream" | "auto";
+type ResponseType =
+  | "json"
+  | "text"
+  | "blob"
+  | "arrayBuffer"
+  | "formData"
+  | "auto";
+
+interface RequestOptions {
+  headers?: Record<string, string>;
+  responseType?: ResponseType;
+  bodyType?: BodyType;
+  signal?: AbortSignal;
+}
+
+export class HestiaNetworkClient {
+  private raw: NetworkClient;
+  private refreshing: Promise<void> | null = null;
+  private refreshFailed = false;
+
+  constructor(
+    private baseUrl: string,
+    private tokens: IdentityProvider,
+    private onAuthStateChanged?: () => void,
+  ) {
+    this.raw = createNetworkClient({
+      baseUrl,
+      defaultResponseType: "json",
+      defaultBodyType: "json",
+      interceptors: {
+        request: [
+          (ctx) => {
+            const access = this.tokens.token("access");
+            if (access) {
+              ctx.headers["Authorization"] = `Bearer ${access}`;
+            }
+            return ctx;
+          },
+        ],
+      },
+    });
+  }
+
+  base() {
+    return this.baseUrl;
+  }
+  async storeTokens(access: string, refresh?: string): Promise<void> {
+    this.refreshFailed = false;
+    await this.tokens.setTokens(access, refresh ?? "");
+  }
+
+  private   async refreshToken(): Promise<void> {
+    if (this.refreshing) return this.refreshing;
+
+    this.refreshing = this.doRefresh();
+    try {
+      await this.refreshing;
+    } finally {
+      this.refreshing = null;
+      this.onAuthStateChanged ? this.onAuthStateChanged() : undefined;
+    }
+  }
+
+  private async doRefresh(): Promise<void> {
+    const refresh = this.tokens.token("refresh");
+    const body = refresh ? { refresh_token: refresh } : {};
+    const res = await this.raw.patch<{
+      data: { token: { access: string; refresh: string } };
+    }>("/system/auth/session", body);
+
+    if (!res.success || !res.data) {
+      this.tokens.clear();
+      this.refreshFailed = true;
+      throw new SystemError({
+        code: "AUTH-002-UNAUTH",
+        message: "Token refresh failed",
+      });
+    }
+
+    const { access, refresh: newRefresh } = res.data.data.token;
+    this.refreshFailed = false;
+    await this.tokens.setTokens(access, newRefresh);
+  }
+
+  private async request<T>(
+    method: HttpMethod,
+    path: string,
+    body?: unknown,
+    options?: RequestOptions,
+  ): Promise<HestiaResponse<T>> {
+    const opts: any = {};
+    if (options?.headers) opts.headers = options.headers;
+    if (options?.responseType) opts.responseType = options.responseType;
+    if (options?.bodyType) opts.bodyType = options.bodyType;
+    if (options?.signal) opts.signal = options.signal;
+
+    let res: ApiResponse<T>;
+
+    if (method === "GET") {
+      res = await this.raw.get<T>(path, opts);
+    } else {
+      const bodyOpts = options?.bodyType
+        ? { type: options.bodyType as BodyType }
+        : undefined;
+      res = (await (this.raw as any)[method.toLowerCase()](
+        path,
+        body,
+        opts,
+        bodyOpts,
+      )) as ApiResponse<T>;
+    }
+
+    if (res.success || res.status === 204) {
+      return new HestiaResponse(res.data as T, res.status);
+    }
+
+    if (
+      (res.status === 401 || res.status === 403) &&
+      !path.includes("/system/auth/token") &&
+      !path.includes("/system/auth/session")
+    ) {
+      // Issue B: API-key requests should never trigger a JWT refresh loop.
+      if (options?.headers?.["X-API-Key"]) {
+        throw new SystemError({
+          code: "AUTH-003-APIKEY",
+          message: "API key is invalid or expired",
+        });
+      }
+
+      // 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();
+        this.onAuthStateChanged?.();
+        throw new SystemError({
+          code: "AUTH-002-UNAUTH",
+          message: "Session expired",
+        });
+      }
+
+      try {
+        await this.refreshToken();
+      } catch {
+        this.tokens.clear();
+        this.onAuthStateChanged?.();
+        throw new SystemError({
+          code: "AUTH-002-UNAUTH",
+          message: "Session expired",
+        });
+      }
+
+      // Issue A: Read the new access token and inject it explicitly so that
+      // an async setTokens (e.g. IndexedDB write) cannot race the interceptor.
+      const newAccess = this.tokens.token("access");
+      const retryOpts: any = { ...opts };
+      if (newAccess) {
+        retryOpts.headers = { ...(opts.headers ?? {}), Authorization: `Bearer ${newAccess}` };
+      }
+
+      if (method === "GET") {
+        res = await this.raw.get<T>(path, retryOpts);
+      } else {
+        const bodyOpts = options?.bodyType
+          ? { type: options.bodyType as BodyType }
+          : undefined;
+        res = (await (this.raw as any)[method.toLowerCase()](
+          path,
+          body,
+          retryOpts,
+          bodyOpts,
+        )) as ApiResponse<T>;
+      }
+
+      if (res.success || res.status === 204) {
+        return new HestiaResponse(res.data as T, res.status);
+      }
+    }
+
+    const errorBody = res.raw ? await parseErrorBody(res.raw) : null;
+    throw toSystemError(res, errorBody);
+  }
+
+  async get<T>(
+    path: string,
+    options?: RequestOptions,
+  ): Promise<HestiaResponse<T>> {
+    return this.request<T>("GET", path, undefined, options);
+  }
+
+  async post<T>(
+    path: string,
+    body?: unknown,
+    options?: RequestOptions,
+  ): Promise<HestiaResponse<T>> {
+    return this.request<T>("POST", path, body, options);
+  }
+
+  async patch<T>(
+    path: string,
+    body?: unknown,
+    options?: RequestOptions,
+  ): Promise<HestiaResponse<T>> {
+    return this.request<T>("PATCH", path, body, options);
+  }
+
+  async put<T>(
+    path: string,
+    body?: unknown,
+    options?: RequestOptions,
+  ): Promise<HestiaResponse<T>> {
+    return this.request<T>("PUT", path, body, options);
+  }
+
+  async delete<T>(
+    path: string,
+    body?: unknown,
+    options?: RequestOptions,
+  ): Promise<HestiaResponse<T>> {
+    return this.request<T>("DELETE", path, body, options);
+  }
+}

package/core/collection.ts

@@ -0,0 +1,121 @@
+import type { QueryDSL } from "@asaidimu/query";
+import { ReactiveDataStore } from "@asaidimu/utils-store";
+import { HestiaNetworkClient } from "./client";
+import { createPagedController, type PageOptions } from "./pager";
+import type {
+    Document,
+    Page,
+    PagedData,
+    PaginationInfo,
+    StoreEvent,
+} from "./types";
+
+interface ServerEnvelope<T extends Record<string, any>> {
+  data: Document<T>[];
+  metadata?: { page?: PaginationInfo };
+}
+
+interface SingleEnvelope<T extends Record<string, any>> {
+  data: Document<T>;
+}
+
+export class HestiaCollection<T extends Record<string, any>> {
+  private pagerOptions: PageOptions<T> = {};
+  private pager: PagedData<T>;
+
+  constructor(
+    private client: HestiaNetworkClient,
+    private collectionName: string,
+  ) {
+    this.pager = createPagedController<T>(
+      collectionName,
+      new ReactiveDataStore<any>({}),
+      this.pagerOptions,
+      (query) => this.find(query),
+    );
+  }
+
+  name() {
+    return this.collectionName;
+  }
+
+  private get queryPath(): string {
+    return `/system/collections/document/${encodeURIComponent(this.collectionName)}/query`;
+  }
+
+  private get documentsPath(): string {
+    return `/system/collections/document/${encodeURIComponent(this.collectionName)}`;
+  }
+
+  private documentPath(id: string): string {
+    return `${this.documentsPath}/${encodeURIComponent(id)}`;
+  }
+
+  async find(query?: QueryDSL<T>): Promise<Page<T>> {
+    const res = await this.client.post<ServerEnvelope<T>>(
+      this.queryPath,
+      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 read(id: string): Promise<Document<T> | undefined> {
+    try {
+      const res = await this.client.get<{ data: Document<T> }>(
+        this.documentPath(id),
+      );
+      return res.data?.data;
+    } catch (err: any) {
+      if (err?.code === "SYNC-001-NF" || err?.code === "NOT_FOUND")
+        return undefined;
+      throw err;
+    }
+  }
+
+  async create(data: Partial<T>): Promise<Document<T>> {
+    const res = await this.client.post<SingleEnvelope<T>>(
+      this.documentsPath,
+      data,
+    );
+    return res.data!.data;
+  }
+
+  async update(id: string, data: Partial<T>): Promise<Document<T>> {
+    const res = await this.client.patch<SingleEnvelope<T>>(
+      this.documentPath(id),
+      data,
+    );
+    return res.data!.data;
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.delete(this.documentPath(id));
+  }
+
+  async subscribe(
+    _scope: string,
+    _callback: (event: StoreEvent) => void,
+  ): Promise<() => void> {
+    throw new Error("Subscription not implemented for dynamic collections");
+  }
+
+  async notify(_event: StoreEvent): Promise<void> {
+    throw new Error("Notify not implemented for dynamic collections");
+  }
+
+  page(): PagedData<T> {
+    return this.pager;
+  }
+}
+
+export type { ServerEnvelope, SingleEnvelope };

package/core/errors.ts

@@ -0,0 +1,55 @@
+import {
+  ApiResponse,
+} from "@asaidimu/network-client"
+import { SystemError, Errors, type Issue } from "@asaidimu/utils-error"
+
+interface ServerErrorBody {
+  code?: string
+  message?: string
+  details?: { issues?: Issue[] }
+}
+
+export async function parseErrorBody(raw: Response): Promise<ServerErrorBody | null> {
+  try {
+    const body = await raw.clone().json() as { error?: ServerErrorBody }
+    return body?.error ?? null
+  } catch {
+    return null
+  }
+}
+
+export function toSystemError(response: ApiResponse<unknown>, body: ServerErrorBody | null): SystemError {
+  if (body) {
+    return new SystemError({
+      code: body.code ?? "UNKNOWN",
+      message: body.message ?? "Unknown error",
+      issues: body.details?.issues,
+    })
+  }
+
+  const rawMsg = response.error?.message
+  if (rawMsg !== null && rawMsg !== undefined && typeof rawMsg === "object") {
+    const obj = rawMsg as Record<string, unknown>
+    return new SystemError({
+      code: (obj.code as string) ?? "UNKNOWN",
+      message: (obj.message as string) ?? "Unknown error",
+    })
+  }
+
+  return new SystemError({
+    code: "UNKNOWN",
+    message: (rawMsg as string) ?? "Unknown error",
+  })
+}
+
+export function notFound(path?: string): SystemError {
+  return Errors.notFound(path)
+}
+
+export function permissionDenied(operation?: string): SystemError {
+  return Errors.permissionDenied(operation)
+}
+
+export function internalError(cause?: unknown): SystemError {
+  return Errors.internalError(cause)
+}

package/core/pager.ts

@@ -0,0 +1,159 @@
+import type { QueryDSL, QueryFilter, SortConfiguration } from "@asaidimu/query";
+import { DELETE_SYMBOL, type DataStore } from "@asaidimu/utils-store";
+import type { Page, PagedData, PagerRefreshOptions } from "./types";
+import { Debouncer } from "@asaidimu/utils-sync";
+
+export interface PageOptions<T extends Record<string, any>> {
+  page?: number;
+  size?: number;
+  sort?: SortConfiguration<T> | SortConfiguration<T>[];
+  filter?: QueryFilter<T>;
+}
+
+const sentinel = {
+  data: [],
+  loading: true,
+  page: {
+    number: 1,
+    size: 20,
+    count: 0,
+    total: 0,
+    pages: 1,
+  },
+};
+export function createPagedController<T extends Record<string, any>>(
+  collectionName: string,
+  store: DataStore<any>,
+  options: PageOptions<T>,
+  find: (query: QueryDSL<T>) => Promise<Page<T>>,
+): PagedData<T> {
+  let currentPage = options.page ?? 1;
+  let currentSize = options.size ?? 20;
+  let currentSort = options.sort;
+  let currentFilter = options.filter;
+  const debounce = new Debouncer({ delay: 50 });
+
+  const CACHE_KEY = `${collectionName}_pager_state_`;
+  store.set({
+    [CACHE_KEY]: {
+      data: [],
+      loading: false,
+      error: DELETE_SYMBOL,
+      page: { number: 1, size: 20, count: 0, total: 0, pages: 1 },
+    },
+  });
+
+  const buildQuery = (opts?: PagerRefreshOptions): QueryDSL<T> => {
+    const page = opts?.page ?? currentPage;
+    const size = opts?.size ?? currentSize;
+    const query: QueryDSL<T> = {
+      pagination: {
+        type: "offset",
+        offset: (page - 1) * size,
+        limit: size,
+      },
+    };
+    const sort = opts?.sort ?? currentSort;
+    if (sort) {
+      query.sort = Array.isArray(sort) ? sort : [sort];
+    }
+    const filter = opts?.filter ?? currentFilter;
+    if (filter) {
+      query.filters = filter;
+    }
+    return query;
+  };
+
+  const load = async (opts?: PagerRefreshOptions) => {
+    await store.set({
+      [CACHE_KEY]: {
+        loading: true,
+        error: DELETE_SYMBOL,
+      },
+    });
+
+    return await new Promise((resolve) => {
+      resolve(
+        debounce.do(async () => {
+          requestIdleCallback(() => {
+            requestIdleCallback(async () => {
+              try {
+                const result = await find(buildQuery(opts));
+                await store.set({ [CACHE_KEY]: result });
+              } catch (error) {
+                await store.set({
+                  [CACHE_KEY]: {
+                    ...sentinel,
+                    error,
+                  },
+                });
+              } finally {
+                await store.set({
+                  [CACHE_KEY]: {
+                    loading: false,
+                  },
+                });
+              }
+            });
+          });
+        }),
+      );
+    });
+  };
+
+  const selector = store.select((s: any) => s[CACHE_KEY]);
+  // TODO: Investigate bug. If by any chance a selectors subscription reaches
+  // zero, it is auto discarded. This might be a problem if we are holding it
+  // fix this
+  const unsub = selector.subscribe(() => {});
+
+  const controller: PagedData<T> = {
+    page: () => selector.get() ?? sentinel,
+
+    navigate: async (page: number) => {
+      if (page < 1) throw new Error("Page number must be >= 1");
+      currentPage = page;
+      await load({
+        page,
+      });
+    },
+
+    resize: async (size: number, page: number) => {
+      if (size < 1) throw new Error("Page size must be >= 1");
+      currentSize = size;
+      currentPage = page;
+      await load();
+    },
+
+    sort: async (sort) => {
+      currentSort = Array.isArray(sort) ? sort : [sort];
+      currentPage = 1;
+      await load();
+    },
+
+    filter: async (filter) => {
+      currentFilter = filter;
+      currentPage = 1;
+      await load();
+    },
+
+    refresh: async (opts) => {
+      await Promise.all([
+        new Promise((resolve) => setTimeout(resolve, opts?.delay || 0)),
+        load(opts),
+      ]);
+    },
+
+    subscribe: (listener) => {
+      return selector.subscribe(listener);
+    },
+
+    invalidate: async () => {
+      await store.set({ [CACHE_KEY]: DELETE_SYMBOL });
+      unsub();
+    },
+
+    id: () => CACHE_KEY,
+  };
+  return controller;
+}