@debros/orama 0.122.4-nightly

package/src/auth/client.ts

@@ -0,0 +1,276 @@
+import { HttpClient } from "../core/http";
+import { AuthConfig, WhoAmI, StorageAdapter, MemoryStorage } from "./types";
+
+export class AuthClient {
+  private httpClient: HttpClient;
+  private storage: StorageAdapter;
+  private currentApiKey?: string;
+  private currentJwt?: string;
+
+  constructor(config: {
+    httpClient: HttpClient;
+    storage?: StorageAdapter;
+    apiKey?: string;
+    jwt?: string;
+  }) {
+    this.httpClient = config.httpClient;
+    this.storage = config.storage ?? new MemoryStorage();
+    this.currentApiKey = config.apiKey;
+    this.currentJwt = config.jwt;
+
+    if (this.currentApiKey) {
+      this.httpClient.setApiKey(this.currentApiKey);
+    }
+    if (this.currentJwt) {
+      this.httpClient.setJwt(this.currentJwt);
+    }
+  }
+
+  setApiKey(apiKey: string) {
+    this.currentApiKey = apiKey;
+    // Don't clear JWT - it will be cleared explicitly on logout
+    this.httpClient.setApiKey(apiKey);
+    this.storage.set("apiKey", apiKey);
+  }
+
+  setJwt(jwt: string) {
+    this.currentJwt = jwt;
+    // Don't clear API key - keep it as fallback for after logout
+    this.httpClient.setJwt(jwt);
+    this.storage.set("jwt", jwt);
+  }
+
+  getToken(): string | undefined {
+    return this.httpClient.getToken();
+  }
+
+  async whoami(): Promise<WhoAmI> {
+    try {
+      const response = await this.httpClient.get<WhoAmI>("/v1/auth/whoami");
+      return response;
+    } catch {
+      return { authenticated: false };
+    }
+  }
+
+  /**
+   * Exchange a stored refresh token for a fresh access token.
+   *
+   * Pulls the refresh token (and the namespace it was issued for) out of
+   * storage — both are persisted by `verify()` after a successful wallet
+   * sign-in. The gateway returns a new access token and may rotate the
+   * refresh token; we persist the rotated one if present.
+   *
+   * Bug #239: previously this method (a) sent no body and (b) read the
+   * wrong response field, so the call always 400-ed AND silently wrote
+   * `undefined` as the in-memory JWT. Both issues fixed.
+   */
+  async refresh(): Promise<string> {
+    const refreshToken = await this.storage.get("refreshToken");
+    if (!refreshToken) {
+      throw new Error(
+        "refresh failed: no refresh token in storage — call verify() first"
+      );
+    }
+    const namespace = (await this.storage.get("namespace")) ?? "default";
+
+    const response = await this.httpClient.post<{
+      access_token: string;
+      refresh_token?: string;
+      expires_in?: number;
+      subject?: string;
+      namespace?: string;
+      token_type?: string;
+    }>("/v1/auth/refresh", { refresh_token: refreshToken, namespace });
+
+    if (!response?.access_token) {
+      throw new Error("refresh failed: server returned no access_token");
+    }
+
+    this.setJwt(response.access_token);
+
+    // Rotate the stored refresh token if the server returned a new one
+    // (rqlite-side gateway currently echoes the same token; future versions
+    // may rotate, so handle both shapes).
+    if (response.refresh_token && response.refresh_token !== refreshToken) {
+      await this.storage.set("refreshToken", response.refresh_token);
+    }
+
+    return response.access_token;
+  }
+
+  /**
+   * Logout user and clear JWT, but preserve API key
+   * Use this for user logout in apps where API key is app-level credential
+   */
+  async logoutUser(): Promise<void> {
+    // Attempt server-side logout if using JWT
+    if (this.currentJwt) {
+      try {
+        await this.httpClient.post("/v1/auth/logout", { all: true });
+      } catch (error) {
+        // Log warning but don't fail - local cleanup is more important
+        console.warn(
+          "Server-side logout failed, continuing with local cleanup:",
+          error
+        );
+      }
+    }
+
+    // Clear JWT only, preserve API key
+    this.currentJwt = undefined;
+    this.httpClient.setJwt(undefined);
+    await this.storage.set("jwt", ""); // Clear JWT from storage
+
+    // Ensure API key is loaded and set as active auth method
+    if (!this.currentApiKey) {
+      // Try to load from storage
+      const storedApiKey = await this.storage.get("apiKey");
+      if (storedApiKey) {
+        this.currentApiKey = storedApiKey;
+      }
+    }
+
+    // Restore API key as the active auth method
+    if (this.currentApiKey) {
+      this.httpClient.setApiKey(this.currentApiKey);
+      console.log("[Auth] API key restored after user logout");
+    } else {
+      console.warn("[Auth] No API key available after logout");
+    }
+  }
+
+  /**
+   * Full logout - clears both JWT and API key
+   * Use this to completely reset authentication state
+   */
+  async logout(): Promise<void> {
+    // Only attempt server-side logout if using JWT
+    // API keys don't support server-side logout with all=true
+    if (this.currentJwt) {
+      try {
+        await this.httpClient.post("/v1/auth/logout", { all: true });
+      } catch (error) {
+        // Log warning but don't fail - local cleanup is more important
+        console.warn(
+          "Server-side logout failed, continuing with local cleanup:",
+          error
+        );
+      }
+    }
+
+    // Always clear local state
+    this.currentApiKey = undefined;
+    this.currentJwt = undefined;
+    this.httpClient.setApiKey(undefined);
+    this.httpClient.setJwt(undefined);
+    await this.storage.clear();
+  }
+
+  async clear(): Promise<void> {
+    this.currentApiKey = undefined;
+    this.currentJwt = undefined;
+    this.httpClient.setApiKey(undefined);
+    this.httpClient.setJwt(undefined);
+    await this.storage.clear();
+  }
+
+  /**
+   * Request a challenge nonce for wallet authentication
+   */
+  async challenge(params: {
+    wallet: string;
+    purpose?: string;
+    namespace?: string;
+  }): Promise<{
+    nonce: string;
+    wallet: string;
+    namespace: string;
+    expires_at: string;
+  }> {
+    const response = await this.httpClient.post("/v1/auth/challenge", {
+      wallet: params.wallet,
+      purpose: params.purpose || "authentication",
+      namespace: params.namespace || "default",
+    });
+    return response;
+  }
+
+  /**
+   * Verify wallet signature and get JWT token
+   */
+  async verify(params: {
+    wallet: string;
+    nonce: string;
+    signature: string;
+    namespace?: string;
+    chain_type?: "ETH" | "SOL";
+  }): Promise<{
+    access_token: string;
+    refresh_token?: string;
+    subject: string;
+    namespace: string;
+    api_key?: string;
+    expires_in?: number;
+    token_type?: string;
+  }> {
+    const response = await this.httpClient.post("/v1/auth/verify", {
+      wallet: params.wallet,
+      nonce: params.nonce,
+      signature: params.signature,
+      namespace: params.namespace || "default",
+      chain_type: params.chain_type || "ETH",
+    });
+
+    // Persist JWT
+    this.setJwt(response.access_token);
+
+    // Persist API key if server provided it (created in verifyHandler)
+    if ((response as any).api_key) {
+      this.setApiKey((response as any).api_key);
+    }
+
+    // Persist refresh token if present (optional, for silent renewal)
+    if ((response as any).refresh_token) {
+      await this.storage.set("refreshToken", (response as any).refresh_token);
+    }
+
+    // Persist the namespace this JWT was issued for so refresh() can
+    // include it in the refresh request body (the gateway scopes refresh
+    // tokens to the issuing namespace). Bug #239 — without this, refresh
+    // would default to "default" and fail for namespace-scoped sessions.
+    const issuedNamespace =
+      (response as any).namespace || params.namespace || "default";
+    await this.storage.set("namespace", issuedNamespace);
+
+    return response as any;
+  }
+
+  /**
+   * Get API key for wallet (creates namespace ownership)
+   */
+  async getApiKey(params: {
+    wallet: string;
+    nonce: string;
+    signature: string;
+    namespace?: string;
+    chain_type?: "ETH" | "SOL";
+  }): Promise<{
+    api_key: string;
+    namespace: string;
+    wallet: string;
+  }> {
+    const response = await this.httpClient.post("/v1/auth/api-key", {
+      wallet: params.wallet,
+      nonce: params.nonce,
+      signature: params.signature,
+      namespace: params.namespace || "default",
+      chain_type: params.chain_type || "ETH",
+    });
+
+    // Automatically set the API key
+    this.setApiKey(response.api_key);
+
+    return response;
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,3 @@
+export { AuthClient } from "./client";
+export type { AuthConfig, WhoAmI, StorageAdapter } from "./types";
+export { MemoryStorage, LocalStorageAdapter } from "./types";

package/src/auth/types.ts

@@ -0,0 +1,62 @@
+export interface AuthConfig {
+  apiKey?: string;
+  jwt?: string;
+}
+
+export interface WhoAmI {
+  address?: string;
+  namespace?: string;
+  authenticated: boolean;
+}
+
+export interface StorageAdapter {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  clear(): Promise<void>;
+}
+
+export class MemoryStorage implements StorageAdapter {
+  private storage: Map<string, string> = new Map();
+
+  async get(key: string): Promise<string | null> {
+    return this.storage.get(key) ?? null;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    this.storage.set(key, value);
+  }
+
+  async clear(): Promise<void> {
+    this.storage.clear();
+  }
+}
+
+export class LocalStorageAdapter implements StorageAdapter {
+  private prefix = "@network/sdk:";
+
+  async get(key: string): Promise<string | null> {
+    if (typeof globalThis !== "undefined" && globalThis.localStorage) {
+      return globalThis.localStorage.getItem(this.prefix + key);
+    }
+    return null;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    if (typeof globalThis !== "undefined" && globalThis.localStorage) {
+      globalThis.localStorage.setItem(this.prefix + key, value);
+    }
+  }
+
+  async clear(): Promise<void> {
+    if (typeof globalThis !== "undefined" && globalThis.localStorage) {
+      const keysToDelete: string[] = [];
+      for (let i = 0; i < globalThis.localStorage.length; i++) {
+        const key = globalThis.localStorage.key(i);
+        if (key?.startsWith(this.prefix)) {
+          keysToDelete.push(key);
+        }
+      }
+      keysToDelete.forEach((key) => globalThis.localStorage.removeItem(key));
+    }
+  }
+}

package/src/cache/client.ts

@@ -0,0 +1,203 @@
+import { HttpClient } from "../core/http";
+import { SDKError } from "../errors";
+
+export interface CacheGetRequest {
+  dmap: string;
+  key: string;
+}
+
+export interface CacheGetResponse {
+  key: string;
+  value: any;
+  dmap: string;
+}
+
+export interface CachePutRequest {
+  dmap: string;
+  key: string;
+  value: any;
+  ttl?: string; // Duration string like "1h", "30m"
+}
+
+export interface CachePutResponse {
+  status: string;
+  key: string;
+  dmap: string;
+}
+
+export interface CacheDeleteRequest {
+  dmap: string;
+  key: string;
+}
+
+export interface CacheDeleteResponse {
+  status: string;
+  key: string;
+  dmap: string;
+}
+
+export interface CacheMultiGetRequest {
+  dmap: string;
+  keys: string[];
+}
+
+export interface CacheMultiGetResponse {
+  results: Array<{
+    key: string;
+    value: any;
+  }>;
+  dmap: string;
+}
+
+export interface CacheScanRequest {
+  dmap: string;
+  match?: string; // Optional regex pattern
+}
+
+export interface CacheScanResponse {
+  keys: string[];
+  count: number;
+  dmap: string;
+}
+
+export interface CacheHealthResponse {
+  status: string;
+  service: string;
+}
+
+export class CacheClient {
+  private httpClient: HttpClient;
+
+  constructor(httpClient: HttpClient) {
+    this.httpClient = httpClient;
+  }
+
+  /**
+   * Check cache service health
+   */
+  async health(): Promise<CacheHealthResponse> {
+    return this.httpClient.get("/v1/cache/health");
+  }
+
+  /**
+   * Get a value from cache
+   * Returns null if the key is not found (cache miss/expired), which is normal behavior
+   */
+  async get(dmap: string, key: string): Promise<CacheGetResponse | null> {
+    try {
+      return await this.httpClient.post<CacheGetResponse>("/v1/cache/get", {
+        dmap,
+        key,
+      });
+    } catch (error) {
+      // Cache misses (404 or "key not found" messages) are normal behavior - return null instead of throwing
+      if (
+        error instanceof SDKError &&
+        (error.httpStatus === 404 ||
+          (error.httpStatus === 500 &&
+            error.message?.toLowerCase().includes("key not found")))
+      ) {
+        return null;
+      }
+      // Re-throw other errors (network issues, server errors, etc.)
+      throw error;
+    }
+  }
+
+  /**
+   * Put a value into cache
+   */
+  async put(
+    dmap: string,
+    key: string,
+    value: any,
+    ttl?: string
+  ): Promise<CachePutResponse> {
+    return this.httpClient.post<CachePutResponse>("/v1/cache/put", {
+      dmap,
+      key,
+      value,
+      ttl,
+    });
+  }
+
+  /**
+   * Delete a value from cache
+   */
+  async delete(dmap: string, key: string): Promise<CacheDeleteResponse> {
+    return this.httpClient.post<CacheDeleteResponse>("/v1/cache/delete", {
+      dmap,
+      key,
+    });
+  }
+
+  /**
+   * Get multiple values from cache in a single request
+   * Returns a map of key -> value (or null if not found)
+   * Gracefully handles 404 errors (endpoint not implemented) by returning empty results
+   */
+  async multiGet(
+    dmap: string,
+    keys: string[]
+  ): Promise<Map<string, any | null>> {
+    try {
+      if (keys.length === 0) {
+        return new Map();
+      }
+
+      const response = await this.httpClient.post<CacheMultiGetResponse>(
+        "/v1/cache/mget",
+        {
+          dmap,
+          keys,
+        }
+      );
+
+      // Convert array to Map
+      const resultMap = new Map<string, any | null>();
+
+      // First, mark all keys as null (cache miss)
+      keys.forEach((key) => {
+        resultMap.set(key, null);
+      });
+
+      // Then, update with found values
+      if (response.results) {
+        response.results.forEach(({ key, value }) => {
+          resultMap.set(key, value);
+        });
+      }
+
+      return resultMap;
+    } catch (error) {
+      // Handle 404 errors silently (endpoint not implemented on backend)
+      // This is expected behavior when the backend doesn't support multiGet yet
+      if (error instanceof SDKError && error.httpStatus === 404) {
+        // Return map with all nulls silently - caller can fall back to individual gets
+        const resultMap = new Map<string, any | null>();
+        keys.forEach((key) => {
+          resultMap.set(key, null);
+        });
+        return resultMap;
+      }
+
+      // Log and return empty results for other errors
+      const resultMap = new Map<string, any | null>();
+      keys.forEach((key) => {
+        resultMap.set(key, null);
+      });
+      console.error(`[CacheClient] Error in multiGet for ${dmap}:`, error);
+      return resultMap;
+    }
+  }
+
+  /**
+   * Scan keys in a distributed map, optionally matching a regex pattern
+   */
+  async scan(dmap: string, match?: string): Promise<CacheScanResponse> {
+    return this.httpClient.post<CacheScanResponse>("/v1/cache/scan", {
+      dmap,
+      match,
+    });
+  }
+}

package/src/cache/index.ts

@@ -0,0 +1,14 @@
+export { CacheClient } from "./client";
+export type {
+  CacheGetRequest,
+  CacheGetResponse,
+  CachePutRequest,
+  CachePutResponse,
+  CacheDeleteRequest,
+  CacheDeleteResponse,
+  CacheMultiGetRequest,
+  CacheMultiGetResponse,
+  CacheScanRequest,
+  CacheScanResponse,
+  CacheHealthResponse,
+} from "./client";