@asaidimu/hestia 1.0.0

package/core/types.ts

@@ -0,0 +1,279 @@
+import { QueryFilter, SortConfiguration } from "@asaidimu/query";
+
+// Internal metadata managed by Anansi
+interface DocumentMetadata {
+  checksum: string; // Integrity hash of the document
+  created: string; // Timestamp (often as a numeric string / nanoseconds)
+  updated: string; // Timestamp (often as a numeric string / nanoseconds)
+  version: number; // Optimistic locking version (increments on each write)
+}
+
+// The base envelope applied to every single document in the system
+interface BaseDocument {
+  _id_: string;
+  _metadata_: DocumentMetadata;
+}
+
+// Generic Document type: base envelope + your custom properties T
+export type Document<T extends Record<string, any>> = BaseDocument & T;
+
+/**
+ * Provides comprehensive pagination information for a collection of records.
+ */
+export type PaginationInfo = {
+  /** The current page number (1-based). */
+  number: number;
+
+  /** The maximum number of items requested per page. */
+  size: number;
+
+  /** The number of items in the current page */
+  count: number;
+
+  /** The total count of all items across all pages. */
+  total: number;
+
+  /** The total number of available pages. */
+  pages: number;
+};
+
+/**
+ * Represents a single paginated response containing a list of records and pagination details.
+ * @template T The type of the records in the page.
+ */
+export interface Page<T extends Record<string, any>> {
+  /** The array of records for the current page. */
+  data: Document<T>[];
+
+  /** Indicates if the data query is currently loading. */
+  loading: boolean;
+
+  /** An error object if the query failed, otherwise `undefined`. */
+  error?: any | undefined;
+
+  /** Pagination metadata providing details about the current page and total collection. */
+  page: PaginationInfo;
+}
+
+export interface PagerRefreshOptions {
+  sort?: SortConfiguration | SortConfiguration[];
+  filter?: QueryFilter;
+  delay?: number;
+  size?: number;
+  page?: number;
+}
+/**
+ * Represents the complete state and control mechanisms for consuming paginated data.
+ * @template T The type of the records in the page (`TableRowData` or an extension).
+ */
+export interface PagedData<T extends Record<string, any>> {
+  id: () => string
+
+  /** The current paginated data, or `undefined` if not found or still loading. */
+  page: () => Page<T>;
+
+  /** Function to fetch a specific page of data.
+   * @param page The 1-based page number to fetch.
+   */
+  navigate: (page: number) => Promise<void>;
+
+  sort: (sort: SortConfiguration<T> | SortConfiguration<T>[]) => Promise<void>;
+  filter: (filter?: QueryFilter<T>) => Promise<void>;
+
+  /**
+   * Function to change the page size of the data
+   */
+  resize: (size: number, page: number) => Promise<void>;
+
+  /**
+   * Function to force a refresh of the current page data, optionally with a delay.
+   * @param delay Optional delay in milliseconds before the refresh operation starts.
+   */
+  refresh: (opts?: PagerRefreshOptions) => Promise<void>;
+
+  /**
+   * Subscribes to page changes.
+   * The callback is invoked immediately with the current page, and then on every
+   * subsequent change (navigation, resize, SSE patch, refresh).
+   *
+   * @param listener A function that receives the current Page<T>.
+   * @returns An unsubscribe function.
+   */
+  subscribe: (listener: (page: Page<T>) => void) => () => void;
+
+  /**
+   * Invalidates the pagination controller, cleaning up any cached resources
+   * (e.g., store subscriptions, in‑flight requests) and removing internal state.
+   * After calling `invalidate()`, the controller should no longer be used.
+   *
+   * This is useful when the component using the pager is unmounted or when
+   * you need to reset the pagination state completely.
+   */
+  invalidate: () => void;
+}
+
+/**
+ * Represents an event emitted by the store, typically for notifications or state changes.
+ */
+export interface StoreEvent {
+  /** The scope of the event, indicating its type and context. Custom scopes are allowed. */
+  scope: string;
+  /** Optional payload carrying data related to the event. */
+  payload?: any;
+}
+
+/**
+ * Defines the core interface for interacting with a remote data store.
+ * @template T The type of the records managed by the store, extending Record.
+ * @template TFindOptions Options for the find operation.
+ * @template TReadOptions Options for the read operation.
+ * @template TListOptions Options for the list operation.
+ * @template TPageOptions Options for the paging operation.
+ * @template TDeleteOptions Options for the delete operation.
+ * @template TUpdateOptions Options for the update operation.
+ * @template TCreateOptions Options for the create operation.
+ * @template TUploadOptions Options for the upload operation.
+ * @template TStreamOptions Options for the stream operation.
+ */
+export interface DocumentStore<
+  T extends Record<string, any>,
+  TFindOptions = Record<string, unknown>,
+  TReadOptions = Record<string, unknown>,
+  TListOptions = Record<string, unknown>,
+  TPageOptions = Record<string, unknown>,
+  TDeleteOptions = Record<string, unknown>,
+  TUpdateOptions = Record<string, unknown>,
+  TCreateOptions = Record<string, unknown>,
+  TUploadOptions = Record<string, unknown>,
+  TStreamOptions = Record<string, unknown>,
+> {
+  /**
+   * Finds records based on provided options, returning a paginated result.
+   * @param options The options for the find operation.
+   * @returns A promise that resolves to a Page of records.
+   */
+  find: (options: TFindOptions) => Promise<Page<T>>;
+
+  /**
+   * Reads a single record by its identifier or other read options.
+   * @param options The options for the read operation, typically including an ID.
+   * @returns A promise that resolves to the record or undefined if not found.
+   */
+  read: (options: TReadOptions) => Promise<Document<T> | undefined>;
+
+  /**
+   * Lists records based on provided options, returning a paginated result.
+   * @param options The options for the list operation.
+   * @returns A promise that resolves to a Page of records.
+   */
+  list: (options: TListOptions) => Promise<Page<T>>;
+
+  /**
+   * Deletes a record based on provided options, typically including an ID.
+   * @param options The options for the delete operation.
+   * @returns A promise that resolves when the deletion is complete.
+   */
+  delete: (options: TDeleteOptions) => Promise<void>;
+
+  /**
+   * Updates an existing record.
+   * @param props An object containing the ID of the record to update, the partial data, and optional update options.
+   * @returns A promise that resolves to the updated record or undefined if not found.
+   */
+  update: (props: {
+    data: Partial<T>;
+    options?: TUpdateOptions;
+  }) => Promise<Document<T> | undefined>;
+
+  /**
+   * Creates a new record.
+   * @param props An object containing the data for the new record and optional create options.
+   * @returns A promise that resolves to the newly created record or undefined if creation failed.
+   */
+  create: (props: {
+    data: Partial<T>;
+    options?: TCreateOptions;
+  }) => Promise<Document<T> | undefined>;
+
+  /**
+   * Uploads a file associated with a record. Optionally updates the record with upload details.
+   * @param props An object containing the file to upload and optional upload options.
+   * @returns A promise that resolves to the updated record after upload or undefined if upload failed.
+   */
+  upload: (props: {
+    file: File;
+    options?: TUploadOptions;
+  }) => Promise<Document<T> | undefined>;
+
+  /**
+   * Subscribes to store events for a given scope.
+   * @param scope The event scope to subscribe to (e.g., 'todos:created:success', '*').
+   * @param callback The function to call when an event matching the scope is received.
+   * @returns A promise that resolves to an unsubscribe function. Call this function to stop receiving events.
+   */
+  subscribe(
+    scope: string,
+    callback: (event: StoreEvent) => void,
+  ): Promise<() => void>;
+  /**
+   * Notifies the store of an event, which can then be broadcast to subscribers.
+   * @param event The StoreEvent to notify.
+   * @returns A promise that resolves when the notification has been processed.
+   */
+  notify: (event: StoreEvent) => Promise<void>;
+
+  /**
+   * Establishes a stream of records based on provided options.
+   * @param options Options for configuring the stream (e.g., batch size, delay, filters).
+   * @param onStreamChange A callback function that is called when the stream's status changes.
+   * @returns An object containing the async iterable stream, a cancel function, and a status getter.
+   */
+  stream: (
+    options: TStreamOptions,
+    onStreamChange: () => void,
+  ) => {
+    /** An async iterable that yields records as they become available in the stream. */
+    stream: () => AsyncIterable<Document<T>>;
+    /** A function to call to cancel the ongoing stream. */
+    cancel: () => void;
+    /** A getter function that returns the current status of the stream ('active', 'cancelled', or 'completed'). */
+    status: () => "active" | "cancelled" | "completed";
+  };
+
+  /**
+   * Creates a paginated data controller for this store.
+   *
+   * @param options - The pagination options, whose type is defined by the
+   *                  store's `TPageOptions` generic parameter. This lets you
+   *                  pass any configuration (e.g., filters, sorting, custom
+   *                  pagination metadata) that your store implementation needs.
+   * @returns A `PagedData<T>` controller that manages loading, navigation,
+   *          resizing, and refresh.
+   *
+   * @example
+   * // Define your store with a custom TPageOptions type
+   * interface MyTodoStore extends DocumentStore<
+   *   Todo,
+   *   FindOptions,
+   *   ReadOptions,
+   *   ListOptions,
+   *   { page: number; size: number; sort?: string; filter?: string }
+   * > {}
+   *
+   * // Use it
+   * const todosPaged = myTodoStore.page({
+   *   page: 1,
+   *   size: 10,
+   *   sort: 'createdAt',
+   *   filter: 'done:false'
+   * });
+   *
+   * // Get current page state
+   * const { data, loading, page } = todosPaged.page();
+   * console.log(`Page ${page.number} of ${page.pages}`);
+   *
+   * // Navigate
+   * await todosPaged.navigate(2);
+   */
+  page(options: TPageOptions): Promise<PagedData<T>>;
+}

package/index.ts

@@ -0,0 +1,62 @@
+// Core
+export { HestiaNetworkClient, HestiaResponse } from "./core/client"
+export type { IdentityProvider  } from "./core/client"
+export { HestiaCollection } from "./core/collection"
+export { toSystemError } from "./core/errors"
+
+// Generic types
+export type { Document, Page, PagedData, PaginationInfo, StoreEvent } from "./core/types"
+
+export type { PageOptions } from "./core/pager"
+
+// Auth
+export { HestiaAuth } from "./auth/store"
+export type { TokenPair, LoginResult, ServerHealth, LoginRequest, RegisterRequest } from "./auth/types"
+
+// System: identity
+export { HestiaUsers } from "./system/identity/store"
+export type {
+  UserData,
+  UserIdentity,
+  CreateUserRequest,
+  UpdateUserRequest,
+} from "./system/identity/types"
+
+// System: api-keys
+export { HestiaKeyStore } from "./system/api-keys/store"
+export type { APIKey, APIKeyWithSecret, CreateKeyRequest, UpdateKeyRequest } from "./system/api-keys/types"
+
+// System: policies
+export { HestiaPolicies } from "./system/policies/store"
+export type {
+  PolicyOperation,
+  PolicyRule,
+  UpsertOperationRequest,
+  UpsertRuleRequest,
+  ValidateRuleRequest,
+  ValidateRuleResult,
+  ReloadResult,
+} from "./system/policies/types"
+
+// System: logs
+export { HestiaLogs } from "./system/logs/store"
+export type { AuditEntry, LogFilter } from "./system/logs/types"
+
+// Blobs
+export { HestiaBlobClient, BlobNamespace } from "./blobs/store"
+export type {
+  NamespaceInfo,
+  BlobMeta,
+  BlobDocument as BlobDoc,
+  ListBlobsRequest,
+  CreateNamespaceRequest,
+} from "./blobs/types"
+
+// Collections
+export { HestiaCollections } from "./collections/store"
+export type { CollectionMeta } from "./collections/types"
+
+// Container
+export { HestiaClient } from "./container"
+
+export * from "./utils"

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@asaidimu/hestia",
+  "version": "1.0.0",
+  "description": "TypeScript client SDK for the Hestia platform — auth, collections, API keys, policies, audit logs, blobs, and capabilities",
+  "type": "module",
+  "module": "index.ts",
+  "main": "index.ts",
+  "types": "index.ts",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:browser": "vitest --browser --run"
+  },
+  "files": [
+    "*.ts",
+    "*/**/*.ts",
+    "!*.test.ts",
+    "!*/**/*.test.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asaidimu/hestia.git"
+  },
+  "license": "MIT",
+  "author": "Asaidimu <dev@asaidimu.com>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@asaidimu/network-client": "^2.0.0",
+    "@asaidimu/utils-artifacts": "^8.2.25",
+    "@asaidimu/utils-error": "^1.1.10",
+    "@asaidimu/utils-store": "^10.2.18",
+    "uuid": "^14.0.1"
+  }
+}

package/system/api-keys/store.ts

@@ -0,0 +1,70 @@
+import type { QueryDSL } from "@asaidimu/query"
+import { HestiaNetworkClient } from "../../core/client"
+import type { Document, Page, PagedData } from "../../core/types"
+import type { APIKey, APIKeyWithSecret, CreateKeyRequest, UpdateKeyRequest } from "./types"
+
+export class HestiaKeyStore {
+  constructor(private client: HestiaNetworkClient) {}
+
+  private basePath = "/system/apikeys/key"
+
+  async find(_query?: QueryDSL<APIKey>): Promise<Page<APIKey>> {
+    const res = await this.client.get<{
+      data: Document<APIKey>[];
+      metadata?: { page?: any };
+    }>(this.basePath)
+    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 }
+  }
+
+  async list(): Promise<Page<APIKey>> {
+    return this.find()
+  }
+
+  async read(id: string): Promise<Document<APIKey> | undefined> {
+    try {
+      const res = await this.client.get<{ data: Document<APIKey> }>(
+        `${this.basePath}/${encodeURIComponent(id)}`,
+      )
+      return res.data?.data
+    } catch (err: any) {
+      if (err?.code === "SYNC-001-NF") return undefined
+      if (err?.code === "INTERNAL_ERROR" && typeof err?.message === "string" && err.message.includes("not found")) return undefined
+      throw err
+    }
+  }
+
+  async create(data: CreateKeyRequest): Promise<Document<APIKeyWithSecret>> {
+    const res = await this.client.post<{ data: Document<APIKeyWithSecret> }>(
+      this.basePath,
+      data,
+    )
+    return res.data!.data
+  }
+
+  async update(id: string, data: UpdateKeyRequest): Promise<Document<APIKey>> {
+    const res = await this.client.patch<{ data: Document<APIKey> }>(
+      `${this.basePath}/${encodeURIComponent(id)}`,
+      data as any,
+    )
+    return res.data!.data
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.delete(`${this.basePath}/${encodeURIComponent(id)}`)
+  }
+
+  async rotate(id: string): Promise<Document<APIKeyWithSecret>> {
+    const res = await this.client.post<{ data: Document<APIKeyWithSecret> }>(
+      `${this.basePath}/${encodeURIComponent(id)}`,
+    )
+    return res.data!.data
+  }
+}

package/system/api-keys/types.ts

@@ -0,0 +1,29 @@
+export interface APIKey {
+  _id_: string
+  name: string
+  prefix: string
+  scopes: string[]
+  status: string
+  expiry?: string | null
+  environment?: string
+  _metadata_: Record<string, unknown>
+}
+
+export interface APIKeyWithSecret extends APIKey {
+  key: string
+}
+
+export interface CreateKeyRequest {
+  name: string
+  environment?: string
+  scopes?: string[]
+  expiry?: string
+}
+
+export interface UpdateKeyRequest {
+  name?: string
+  environment?: string
+  scopes?: string[]
+  status?: "active" | "revoked"
+  expiry?: string
+}

package/system/capabilities/store.ts

@@ -0,0 +1,23 @@
+import { HestiaNetworkClient } from "../../core/client";
+import type { Document } from "../../core/types";
+
+export class HestiaCapabilities {
+  constructor(
+    private client: HestiaNetworkClient,
+  ) {
+
+  }
+
+  async fetch(): Promise<Array<Document<any>> | undefined> {
+    try {
+      const res = await this.client.get<{ data: Array<Document<any>> }>(
+        `/system/core/docs`,
+      );
+      return res.data?.data;
+    } catch (err: any) {
+      if (err?.code === "SYNC-001-NF") return undefined;
+      throw err;
+    }
+  }
+
+}

package/system/capabilities/types.ts

@@ -0,0 +1 @@
+// Capabilities types — currently empty

package/system/identity/store.ts

@@ -0,0 +1,90 @@
+import type { QueryDSL } from "@asaidimu/query";
+import { ReactiveDataStore } from "@asaidimu/utils-store";
+import { HestiaNetworkClient } from "../../core/client";
+import { createPagedController } from "../../core/pager";
+import type { Document, Page, PagedData } from "../../core/types";
+import type { UpdateUserRequest, UserData } from "./types";
+
+export class HestiaUsers {
+  private pagerOptions: any = {};
+  private pager: PagedData<UserData>;
+
+  constructor(
+    private client: HestiaNetworkClient,
+  ) {
+    this.pager = createPagedController<UserData>(
+      "users",
+      new ReactiveDataStore<any>({}),
+      this.pagerOptions,
+      (query) => this.find(query),
+    );
+  }
+
+  name() {
+    return "users";
+  }
+
+  async find(query?: QueryDSL<UserData>): Promise<Page<UserData>> {
+    const res = await this.client.post<{
+      data:  Document<UserData>[];
+      metadata?: { page?: any };
+    }>("/system/users/user/query", query ?? {});
+    const data = res.data?.data ?? [];
+    const pageMeta = res.data?.metadata?.page ?? {
+      number: 1,
+      size: data.length,
+      count: data.length,
+      total: data.length,
+      pages: 1,
+    };
+    return { data, loading: false, page: pageMeta };
+  }
+
+  async list(options?: QueryDSL<UserData>): Promise<Page<UserData>> {
+    return this.find(
+      options ?? { pagination: { type: "offset", offset: 0, limit: 50 } },
+    );
+  }
+
+  async read(id: string): Promise<Document<UserData> | undefined> {
+    try {
+      const res = await this.client.get<{ data: Document<UserData> }>(
+        `/system/users/user/${encodeURIComponent(id)}`,
+      );
+      return res.data?.data;
+    } catch (err: any) {
+      if (err?.code === "SYNC-001-NF") return undefined;
+      throw err;
+    }
+  }
+
+  async update(
+    id: string,
+    data: UpdateUserRequest,
+  ): Promise<Document<UserData>> {
+    const res = await this.client.patch<{ data: Document<UserData> }>(
+      `/system/users/user/${encodeURIComponent(id)}`,
+      data as any,
+    );
+    return res.data!.data;
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.delete(`/system/users/user/${encodeURIComponent(id)}`);
+  }
+
+  async changePassword(
+    userId: string,
+    current: string,
+    newPassword: string,
+  ): Promise<void> {
+    await this.client.patch(`/system/users/password/${encodeURIComponent(userId)}`, {
+      current,
+      new: newPassword,
+    });
+  }
+
+  page(): PagedData<UserData> {
+    return this.pager;
+  }
+}

package/system/identity/types.ts

@@ -0,0 +1,31 @@
+import { Document } from "../../core/types"
+
+export interface UserData {
+  email: string
+  name: string
+  verified: boolean
+  scopes: string[]
+  deleted_at?: string | null
+}
+
+export type UserIdentity = Document<UserData>
+
+export interface CreateUserRequest {
+  email: string
+  password: string
+  name: string
+  scopes?: string[]
+  verified?: boolean
+}
+
+export interface UpdateUserRequest {
+  name?: string
+  email?: string
+  scopes?: string[]
+  verified?: boolean
+}
+
+export interface ChangePasswordRequest {
+  current: string
+  new: string
+}