@objectstack/client 4.0.2 → 4.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/client",
-  "version": "4.0.2",
+  "version": "4.0.4",
   "license": "Apache-2.0",
   "description": "Official Client SDK for ObjectStack Protocol",
   "main": "dist/index.js",
@@ -13,20 +13,20 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "4.0.2",
-    "@objectstack/spec": "4.0.2"
+    "@objectstack/core": "4.0.4",
+    "@objectstack/spec": "4.0.4"
   },
   "devDependencies": {
-    "@hono/node-server": "^1.19.12",
-    "msw": "^2.12.14",
+    "@hono/node-server": "^1.19.14",
+    "msw": "^2.13.2",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.2",
-    "@objectstack/driver-memory": "4.0.2",
-    "@objectstack/hono": "4.0.2",
-    "@objectstack/objectql": "4.0.2",
-    "@objectstack/plugin-hono-server": "4.0.2",
-    "@objectstack/plugin-msw": "4.0.2",
-    "@objectstack/runtime": "4.0.2"
+    "vitest": "^4.1.4",
+    "@objectstack/driver-memory": "4.0.4",
+    "@objectstack/hono": "4.0.4",
+    "@objectstack/objectql": "4.0.4",
+    "@objectstack/plugin-hono-server": "4.0.4",
+    "@objectstack/plugin-msw": "4.0.4",
+    "@objectstack/runtime": "4.0.4"
   },
   "scripts": {
     "build": "tsup --config ../../tsup.config.ts",

package/src/client.hono.test.ts

@@ -107,11 +107,19 @@ describe('ObjectStackClient (with Hono Server)', () => {
         baseUrl = `http://localhost:${port}`;
 
         console.log(`Test server running at ${baseUrl}`);
-    });
+    }, 30_000);
 
     afterAll(async () => {
-        if (kernel) await kernel.shutdown();
-    });
+        if (kernel) {
+            // Race shutdown against a hard deadline.
+            // kernel.shutdown() can hang when pino's flush callback never fires
+            // in CI (worker-thread transport timing issues), so cap the wait.
+            await Promise.race([
+                kernel.shutdown(),
+                new Promise<void>((resolve) => setTimeout(resolve, 10_000)),
+            ]);
+        }
+    }, 30_000);
 
     it('should connect to hono server and discover endpoints', async () => {
         const client = new ObjectStackClient({ baseUrl });

package/src/index.ts

@@ -1,9 +1,9 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { QueryAST, SortNode, AggregationNode, isFilterAST } from '@objectstack/spec/data';
-import { 
-  BatchUpdateRequest, 
-  BatchUpdateResponse, 
+import {
+  BatchUpdateRequest,
+  BatchUpdateResponse,
   UpdateManyRequest,
   DeleteManyRequest,
   BatchOptions,
@@ -88,6 +88,7 @@ import {
   ApiRoutes,
 } from '@objectstack/spec/api';
 import { Logger, createLogger } from '@objectstack/core';
+import { RealtimeAPI } from './realtime-api';
 
 /**
  * Route types that the client can resolve.
@@ -228,18 +229,22 @@ export class ObjectStackClient {
   private fetchImpl: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
   private discoveryInfo?: DiscoveryResult;
   private logger: Logger;
+  private realtimeAPI: RealtimeAPI;
 
   constructor(config: ClientConfig) {
     this.baseUrl = config.baseUrl.replace(/\/$/, ''); // Remove trailing slash
     this.token = config.token;
     this.fetchImpl = config.fetch || globalThis.fetch.bind(globalThis);
-    
+
     // Initialize logger
-    this.logger = config.logger || createLogger({ 
+    this.logger = config.logger || createLogger({
       level: config.debug ? 'debug' : 'info',
       format: 'pretty'
     });
-    
+
+    // Initialize realtime API
+    this.realtimeAPI = new RealtimeAPI(this.baseUrl, this.token);
+
     this.logger.debug('ObjectStack client created', { baseUrl: this.baseUrl });
   }
 
@@ -248,12 +253,26 @@ export class ObjectStackClient {
    */
   async connect() {
     this.logger.debug('Connecting to ObjectStack server', { baseUrl: this.baseUrl });
-    
+
     try {
       let data: DiscoveryResult | undefined;
 
-      // 1. Try Standard Discovery (.well-known)
+      // 1. Try Protocol-standard Discovery Path /api/v1/discovery (primary)
       try {
+        const discoveryUrl = `${this.baseUrl}/api/v1/discovery`;
+        this.logger.debug('Probing protocol-standard discovery endpoint', { url: discoveryUrl });
+        const res = await this.fetchImpl(discoveryUrl);
+        if (res.ok) {
+          const body = await res.json();
+          data = body.data || body;
+          this.logger.debug('Discovered via /api/v1/discovery');
+        }
+      } catch (e) {
+        this.logger.debug('Protocol-standard discovery probe failed', { error: (e as Error).message });
+      }
+
+      // 2. Fallback to Standard Discovery (.well-known)
+      if (!data) {
         let wellKnownUrl: string;
         try {
           // If baseUrl is absolute, get origin
@@ -264,24 +283,10 @@ export class ObjectStackClient {
           wellKnownUrl = '/.well-known/objectstack';
         }
 
-        this.logger.debug('Probing .well-known discovery', { url: wellKnownUrl });
+        this.logger.debug('Falling back to .well-known discovery', { url: wellKnownUrl });
         const res = await this.fetchImpl(wellKnownUrl);
-        if (res.ok) {
-          const body = await res.json();
-          data = body.data || body;
-          this.logger.debug('Discovered via .well-known');
-        }
-      } catch (e) {
-        this.logger.debug('Standard discovery probe failed', { error: (e as Error).message });
-      }
-
-      // 2. Fallback to Protocol-standard Discovery Path /api/v1/discovery
-      if (!data) {
-        const fallbackUrl = `${this.baseUrl}/api/v1/discovery`;
-        this.logger.debug('Falling back to standard discovery endpoint', { url: fallbackUrl });
-        const res = await this.fetchImpl(fallbackUrl);
         if (!res.ok) {
-           throw new Error(`Failed to connect to ${fallbackUrl}: ${res.statusText}`);
+           throw new Error(`Failed to connect to ${wellKnownUrl}: ${res.statusText}`);
         }
         const body = await res.json();
         data = body.data || body;
@@ -292,13 +297,13 @@ export class ObjectStackClient {
       }
 
       this.discoveryInfo = data;
-      
-      this.logger.info('Connected to ObjectStack server', { 
+
+      this.logger.info('Connected to ObjectStack server', {
         version: data.version,
         apiName: data.apiName,
-        services: data.services 
+        services: data.services
       });
-      
+
       return data as DiscoveryResult;
     } catch (e) {
       this.logger.error('Failed to connect to ObjectStack server', e as Error, { baseUrl: this.baseUrl });
@@ -573,6 +578,16 @@ export class ObjectStackClient {
    * Authentication Services
    */
   auth = {
+    /**
+     * Get authentication configuration
+     * Returns available auth providers and features
+     */
+    getConfig: async () => {
+      const route = this.getRoute('auth');
+      const res = await this.fetch(`${this.baseUrl}${route}/config`);
+      return this.unwrapResponse(res);
+    },
+
     /**
      * Login with email and password
      * Uses better-auth endpoint: POST /sign-in/email
@@ -887,6 +902,14 @@ export class ObjectStackClient {
       },
   };
 
+  /**
+   * Event Subscription API
+   * Provides real-time event subscriptions for metadata and data changes
+   */
+  get events() {
+    return this.realtimeAPI;
+  }
+
   /**
    * Permissions Services
    */
@@ -1789,6 +1812,9 @@ export class ObjectStackClient {
 // Re-export type-safe query builder
 export { QueryBuilder, FilterBuilder, createQuery, createFilter } from './query-builder';
 
+// Re-export realtime API types
+export { RealtimeAPI, RealtimeSubscriptionFilter, RealtimeEventHandler } from './realtime-api';
+
 // Re-export commonly used types from @objectstack/spec/api for convenience
 export type {
   BatchUpdateRequest,
@@ -1856,4 +1882,8 @@ export type {
   SubscribeResponse,
   UnsubscribeResponse,
   WellKnownCapabilities,
+  GetAuthConfigResponse,
+  AuthProviderInfo,
+  EmailPasswordConfigPublic,
+  AuthFeaturesConfig,
 } from '@objectstack/spec/api';

package/src/realtime-api.ts

@@ -0,0 +1,208 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Realtime API Module for ObjectStackClient
+ *
+ * Provides real-time event subscription capabilities using long-polling.
+ * For production WebSocket/SSE support, extend with transport adapters.
+ */
+
+import type { RealtimeEventPayload } from '@objectstack/spec/contracts';
+import type { MetadataEvent, DataEvent } from '@objectstack/spec/api';
+
+export interface RealtimeSubscriptionFilter {
+  /** Metadata/object type filter */
+  type?: string;
+  /** Package ID filter */
+  packageId?: string;
+  /** Event types to listen for */
+  eventTypes?: string[];
+  /** Record ID filter (for data events) */
+  recordId?: string;
+}
+
+export type RealtimeEventHandler = (event: RealtimeEventPayload) => void;
+
+/**
+ * Realtime API for subscribing to server events
+ *
+ * Note: Currently uses in-memory adapter. WebSocket/SSE transport planned for future.
+ */
+export class RealtimeAPI {
+  // @ts-expect-error - Reserved for future WebSocket/SSE implementation
+  private _baseUrl: string;
+  // @ts-expect-error - Reserved for future WebSocket/SSE implementation
+  private _token?: string;
+  private subscriptions = new Map<string, {
+    filter: RealtimeSubscriptionFilter;
+    handler: RealtimeEventHandler;
+  }>();
+  private pollInterval?: ReturnType<typeof setInterval>;
+  private eventBuffer: RealtimeEventPayload[] = [];
+
+  constructor(baseUrl: string, token?: string) {
+    this._baseUrl = baseUrl;
+    this._token = token;
+  }
+
+  /**
+   * Subscribe to metadata events
+   * Returns an unsubscribe function
+   */
+  subscribeMetadata(
+    type: string,
+    callback: (event: MetadataEvent) => void,
+    options?: { packageId?: string }
+  ): () => void {
+    const subscriptionId = `metadata-${type}-${Date.now()}`;
+
+    this.subscriptions.set(subscriptionId, {
+      filter: {
+        type,
+        packageId: options?.packageId,
+        eventTypes: [
+          `metadata.${type}.created`,
+          `metadata.${type}.updated`,
+          `metadata.${type}.deleted`
+        ]
+      },
+      handler: (event) => {
+        // Type guard and filter
+        if (event.type.startsWith('metadata.')) {
+          callback(event as any as MetadataEvent);
+        }
+      }
+    });
+
+    // Start polling if not already started
+    this.startPolling();
+
+    // Return unsubscribe function
+    return () => {
+      this.subscriptions.delete(subscriptionId);
+      if (this.subscriptions.size === 0) {
+        this.stopPolling();
+      }
+    };
+  }
+
+  /**
+   * Subscribe to data record events
+   * Returns an unsubscribe function
+   */
+  subscribeData(
+    object: string,
+    callback: (event: DataEvent) => void,
+    options?: { recordId?: string }
+  ): () => void {
+    const subscriptionId = `data-${object}-${Date.now()}`;
+
+    this.subscriptions.set(subscriptionId, {
+      filter: {
+        type: object,
+        recordId: options?.recordId,
+        eventTypes: [
+          'data.record.created',
+          'data.record.updated',
+          'data.record.deleted'
+        ]
+      },
+      handler: (event) => {
+        // Type guard and filter
+        if (event.type.startsWith('data.') && event.object === object) {
+          if (!options?.recordId || (event.payload as any)?.recordId === options.recordId) {
+            callback(event as any as DataEvent);
+          }
+        }
+      }
+    });
+
+    // Start polling if not already started
+    this.startPolling();
+
+    // Return unsubscribe function
+    return () => {
+      this.subscriptions.delete(subscriptionId);
+      if (this.subscriptions.size === 0) {
+        this.stopPolling();
+      }
+    };
+  }
+
+  /**
+   * Emit an event to all matching subscriptions (client-side only)
+   * This is used for in-process event delivery
+   */
+  private emitEvent(event: RealtimeEventPayload): void {
+    for (const sub of this.subscriptions.values()) {
+      // Check if event matches subscription filters
+      const matchesType = !sub.filter.type ||
+        event.type.includes(sub.filter.type) ||
+        event.object === sub.filter.type;
+
+      const matchesEventType = !sub.filter.eventTypes?.length ||
+        sub.filter.eventTypes.includes(event.type);
+
+      const matchesPackage = !sub.filter.packageId ||
+        (event.payload as any)?.packageId === sub.filter.packageId;
+
+      if (matchesType && matchesEventType && matchesPackage) {
+        try {
+          sub.handler(event);
+        } catch (error) {
+          console.error('Error in realtime event handler:', error);
+        }
+      }
+    }
+  }
+
+  /**
+   * Start polling for events (fallback mechanism)
+   * In production, this would be replaced with WebSocket/SSE
+   */
+  private startPolling(): void {
+    if (this.pollInterval) return;
+
+    // For now, we rely on the in-memory adapter within the same process
+    // Events are delivered synchronously via the IRealtimeService
+    // This polling is a placeholder for future WebSocket/SSE implementation
+
+    // Poll every 2 seconds for buffered events
+    this.pollInterval = setInterval(() => {
+      // Process any buffered events
+      while (this.eventBuffer.length > 0) {
+        const event = this.eventBuffer.shift();
+        if (event) {
+          this.emitEvent(event);
+        }
+      }
+    }, 2000);
+  }
+
+  /**
+   * Stop polling for events
+   */
+  private stopPolling(): void {
+    if (this.pollInterval) {
+      clearInterval(this.pollInterval);
+      this.pollInterval = undefined;
+    }
+  }
+
+  /**
+   * Internal method to buffer events from server
+   * This would be called by WebSocket/SSE handlers in production
+   */
+  _bufferEvent(event: RealtimeEventPayload): void {
+    this.eventBuffer.push(event);
+  }
+
+  /**
+   * Disconnect and clean up all subscriptions
+   */
+  disconnect(): void {
+    this.stopPolling();
+    this.subscriptions.clear();
+    this.eventBuffer = [];
+  }
+}

package/tests/integration/01-discovery.test.ts

@@ -13,15 +13,15 @@ import { ObjectStackClient } from '../../src/index';
 const TEST_SERVER_URL = process.env.TEST_SERVER_URL || 'http://localhost:3000';
 
 describe('Discovery & Connection', () => {
-  describe('TC-DISC-001: Standard Discovery via .well-known', () => {
-    test('should discover API from .well-known/objectstack', async () => {
-      const client = new ObjectStackClient({ 
+  describe('TC-DISC-001: Protocol-standard Discovery via /api/v1/discovery', () => {
+    test('should discover API from /api/v1/discovery', async () => {
+      const client = new ObjectStackClient({
         baseUrl: TEST_SERVER_URL,
         debug: true
       });
-      
+
       const discovery = await client.connect();
-      
+
       expect(discovery.version).toBeDefined();
       expect(discovery.apiName).toBeDefined();
       expect(discovery.routes).toBeDefined();