@fatagnus/dink-sdk 2.24.0 → 2.24.1

package/dist/edge/index.d.ts

@@ -1,4 +1,501 @@
-export { EdgeClient } from './client.js';
-export { ServiceBuilder } from './service-builder.js';
-export { createEdgeWorker, type EdgeWorkerOptions, type EdgeWorkerHandle, type EdgeConnection } from './worker.js';
-//# sourceMappingURL=index.d.ts.map
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * Service definition metadata
+ */
+export interface ServiceDefinition {
+	name: string;
+	version: string;
+	methods: string[];
+}
+/**
+ * Interface for implementing a service handler on the edge
+ */
+/** Bidirectional raw byte channel on the edge side. */
+export interface EdgeChannel {
+	/** Unique channel identifier (e.g., "ch_abc123") */
+	readonly id: string;
+	/** Send raw bytes to the browser. Returns false if backpressure is active. */
+	write(data: Uint8Array): boolean;
+	/** Register handler for incoming raw bytes from browser */
+	onData(handler: (data: Uint8Array) => void): void;
+	/** Close the channel, optionally with a reason */
+	close(reason?: string): void;
+	/** Called when the channel closes (by either side). Supports multiple handlers. */
+	onClose(handler: (reason?: string) => void): void;
+	/** Send a JSON-serializable control message out-of-band */
+	sendControl(msg: unknown): void;
+	/** Register handler for incoming control messages */
+	onControl(handler: (msg: unknown) => void): void;
+	/** True if channel is open */
+	readonly isOpen: boolean;
+	/** Promise that resolves when the channel closes */
+	readonly closed: Promise<void>;
+	/** Number of bytes queued for sending */
+	readonly bufferedAmount: number;
+	/** Register handler called when buffered data has been flushed */
+	onDrain(handler: () => void): void;
+}
+/**
+ */
+export interface ServiceHandler {
+	definition(): ServiceDefinition;
+	handleRequest(method: string, data: Uint8Array): Promise<Uint8Array>;
+	handleStream?(method: string, data: Uint8Array, emit: (data: Uint8Array) => Promise<void>, signal?: AbortSignal): Promise<void>;
+	handleChannel?(method: string, channel: EdgeChannel, request: unknown): Promise<void>;
+}
+/**
+ * Interface for making RPC calls to edge services
+ */
+export interface ServiceCaller {
+	call<Req, Resp>(edgeId: string, service: string, method: string, req: Req): Promise<Resp>;
+	subscribe<Req, Resp>(edgeId: string, service: string, method: string, req: Req, handler: (resp: Resp) => void): Promise<Subscription>;
+}
+/**
+ * Interface for streaming subscriptions
+ */
+export interface Subscription {
+	unsubscribe(): void;
+}
+/**
+ * Connection quality level
+ */
+export type ConnectionQualityLevel = "excellent" | "good" | "fair" | "poor" | "unknown";
+/**
+ * Connection state
+ */
+export type ConnectionState = "connecting" | "connected" | "reconnecting" | "disconnected";
+/**
+ * Connection quality metrics
+ */
+export interface ConnectionQuality {
+	state: ConnectionState;
+	latencyMs: number | null;
+	avgLatencyMs: number | null;
+	messagesSentPerSecond: number;
+	messagesReceivedPerSecond: number;
+	totalMessagesSent: number;
+	totalMessagesReceived: number;
+	lastPingAt: number | null;
+	qualityLevel: ConnectionQualityLevel;
+}
+/**
+ * Configuration for connection quality monitoring
+ */
+export interface ConnectionQualityConfig {
+	/** Latency threshold for "excellent" quality in ms (default: 50) */
+	excellentLatencyMs?: number;
+	/** Latency threshold for "good" quality in ms (default: 150) */
+	goodLatencyMs?: number;
+	/** Latency threshold for "fair" quality in ms (default: 300) */
+	fairLatencyMs?: number;
+	/** Ping interval in milliseconds (default: 30000) */
+	pingIntervalMs?: number;
+}
+/**
+ * Configuration for EdgeClient
+ */
+export interface EdgeConfig {
+	/** Edge API key (required, format: base64 JSON with url+secret, or legacy dk_<env>_ed_<appID>_<edgeID>_<random>) */
+	apiKey: string;
+	/** dinkd server URL (e.g., "nats://localhost:4222"). Optional if using new key format with embedded URL. */
+	serverUrl?: string;
+	/** Optional display name for the edge */
+	edgeName?: string;
+	/** Optional labels for edge discovery */
+	labels?: Record<string, string>;
+	/** Optional version string */
+	version?: string;
+	/** Optional hostname (auto-detected in Node.js) */
+	hostname?: string;
+	/** Optional IP address */
+	ipAddress?: string;
+	/** Heartbeat interval in ms (default: 30000) */
+	heartbeatInterval?: number;
+	/** Connection/request timeout in ms (default: 30000) */
+	timeout?: number;
+	/** Reconnect wait time in ms (default: 2000) */
+	reconnectWait?: number;
+	/** Max reconnect attempts, -1 for infinite (default: -1) */
+	maxReconnects?: number;
+	/** Connection quality configuration */
+	qualityConfig?: ConnectionQualityConfig;
+}
+/**
+ * Information about a discovered edge
+ */
+export interface EdgeInfo {
+	/** Unique edge identifier */
+	id: string;
+	/** Display name of the edge */
+	name: string;
+	/** Online status */
+	status: "online" | "offline";
+	/** Labels attached to the edge */
+	labels: Record<string, string>;
+	/** Services exposed by this edge */
+	services: string[];
+	/** Groups this edge belongs to */
+	groups?: string[];
+}
+/**
+ * Options for discovering edges
+ */
+export interface DiscoverOptions {
+	/** Filter by service name */
+	serviceName?: string;
+	/** Filter by labels */
+	labels?: Record<string, string>;
+	/** Only return online edges (default: true) */
+	onlineOnly?: boolean;
+	/** Filter by method name (requires serviceName) */
+	methodName?: string;
+}
+/**
+ * Options for RPC calls
+ */
+export interface CallOptions {
+	/** Request timeout in ms */
+	timeout?: number;
+	/** Number of retries on failure (default: 0) */
+	retries?: number;
+	/** Delay between retries in ms (default: 1000) */
+	retryDelay?: number;
+}
+/**
+ * Service introspection types for AI agent support.
+ * These types match the Go struct definitions in pkg/types/introspect.go
+ * Property names use snake_case to match Go JSON tags for wire compatibility.
+ */
+/**
+ * MethodAIContext provides AI-specific guidance for understanding and using a method.
+ */
+export interface MethodAIContext {
+	/** When this method should be called */
+	when_to_use?: string;
+	/** Why to use this method over alternatives */
+	why_to_use?: string;
+	/** Instructions on how to use this method correctly */
+	how_to_use?: string;
+	/** Conditions that must be true before calling this method */
+	preconditions?: string[];
+	/** Side effects that occur when calling this method */
+	side_effects?: string[];
+	/** Names of related methods that may be useful */
+	related_methods?: string[];
+	/** Scenarios describing when to use this method */
+	scenarios?: string[];
+}
+/**
+ * ServiceAIContext provides AI-specific guidance for understanding a service.
+ */
+export interface ServiceAIContext {
+	/** High-level description of what this service does */
+	overview?: string;
+	/** List of capabilities this service provides */
+	capabilities?: string[];
+	/** Known limitations of this service */
+	limitations?: string[];
+}
+/**
+ * MethodDescriptor provides complete metadata about a service method for introspection
+ * and AI agent consumption.
+ */
+export interface MethodDescriptor {
+	/** Method name */
+	name: string;
+	/** Human-readable description of what this method does */
+	description?: string;
+	/** JSON Schema describing the input parameters */
+	input_schema?: Record<string, unknown>;
+	/** JSON Schema describing the output */
+	output_schema?: Record<string, unknown>;
+	/** Tags for categorization and filtering */
+	tags?: string[];
+	/** AI-specific context for this method */
+	ai_context?: MethodAIContext;
+}
+/**
+ * ServiceDescriptor provides complete metadata about a service for introspection
+ * and AI agent consumption.
+ */
+export interface ServiceDescriptor {
+	/** Service name */
+	name: string;
+	/** Service version (semver recommended) */
+	version: string;
+	/** Human-readable description of this service */
+	description?: string;
+	/** Methods provided by this service */
+	methods?: MethodDescriptor[];
+	/** AI-specific context for this service */
+	ai_context?: ServiceAIContext;
+	/** Names of related services */
+	related_services?: string[];
+}
+export declare class EdgeClient {
+	private config;
+	private nc;
+	private services;
+	private heartbeatTimer;
+	private pingTimer;
+	private appId;
+	private edgeId;
+	private connectionState;
+	private lastLatencyMs;
+	private lastPingAt;
+	private latencyHistory;
+	private messagesSent;
+	private messagesReceived;
+	private statsStartedAt;
+	private qualityCallbacks;
+	private qualityConfig;
+	private groups;
+	constructor(config: EdgeConfig);
+	connect(): Promise<void>;
+	disconnect(): Promise<void>;
+	exposeService(handler: ServiceHandler): Promise<void>;
+	private handleStreamRequest;
+	private handleChannelRequest;
+	unexposeService(name: string): Promise<void>;
+	isConnected(): boolean;
+	/** Returns the edge ID (extracted from the API key) */
+	getEdgeId(): string;
+	/** Returns the app ID (extracted from the API key) */
+	getAppId(): string;
+	/**
+	 * Get the ServiceDescriptor for an exposed service.
+	 * Returns null if the service is not found.
+	 * @param serviceName - The name of the service to describe
+	 */
+	getServiceDescriptor(serviceName: string): ServiceDescriptor | null;
+	/** Returns the groups this edge belongs to */
+	getGroups(): string[];
+	/**
+	 * Expose a service to group peers.
+	 * Subscribes to both directed and broadcast subjects for each group.
+	 */
+	exposePeerService(handler: ServiceHandler): Promise<void>;
+	/**
+	 * Call a peer edge's service within a group.
+	 */
+	callPeer<Req, Resp>(groupId: string, edgeId: string, service: string, method: string, req: Req, opts?: CallOptions): Promise<Resp>;
+	/**
+	 * Call a service on any peer in the group (broadcast/queue).
+	 */
+	callGroup<Req, Resp>(groupId: string, service: string, method: string, req: Req, opts?: CallOptions): Promise<Resp>;
+	/**
+	 * Call a center service that is exposed to a specific group.
+	 */
+	callCenterGroup<Req, Resp>(groupId: string, service: string, method: string, req: Req, opts?: CallOptions): Promise<Resp>;
+	/**
+	 * Create a ServiceCaller scoped to a specific group for directed peer-to-peer RPC.
+	 * The returned caller routes through callPeer, so generated typed clients
+	 * (e.g., MarketWatcherService.Client) work with edge-to-edge calls.
+	 *
+	 * @example
+	 * const caller = edge.groupCaller('trading-team');
+	 * const client = new MarketWatcherService.Client('market-watcher', caller);
+	 * const snapshot = await client.GetMarketSnapshot({ pair: 'BTC/USDT' });
+	 */
+	groupCaller(groupId: string): ServiceCaller;
+	/**
+	 * Create a ServiceCaller scoped to a specific group for broadcast/queue-based RPC.
+	 * The edgeId parameter in call() is ignored — one random peer in the group handles it.
+	 */
+	groupBroadcastCaller(groupId: string): ServiceCaller;
+	/**
+	 * Unwrap a peer/group service response, handling { result } wrapper and error responses.
+	 */
+	private unwrapPeerResponse;
+	/**
+	 * Discover peers within a group.
+	 */
+	discoverPeers(groupId: string, opts?: DiscoverOptions): Promise<EdgeInfo[]>;
+	/**
+	 * Get current connection quality metrics.
+	 */
+	getConnectionQuality(): ConnectionQuality;
+	/**
+	 * Subscribe to connection quality changes.
+	 * @param callback - Function called with updated quality metrics
+	 * @returns Unsubscribe function
+	 */
+	onConnectionQualityChange(callback: (quality: ConnectionQuality) => void): () => void;
+	/**
+	 * Ping the server and return round-trip latency in milliseconds.
+	 */
+	ping(): Promise<number>;
+	private setConnectionState;
+	private calculateQualityLevel;
+	private calculateAvgLatency;
+	private buildQualitySnapshot;
+	private emitQualityChange;
+	private setupConnectionHandlers;
+	private startPingTimer;
+	private stopPingTimer;
+	private extractMethod;
+	private registerPresence;
+	private deregisterPresence;
+	private registerService;
+	private deregisterService;
+	/** Register a webhook endpoint with dinkd. */
+	registerWebhook(service: string, method: string, secret: string, secretMode: string, description: string): Promise<Record<string, unknown>>;
+	/** Remove a webhook registration. */
+	deregisterWebhook(webhookId: string): Promise<void>;
+	/** List all registered webhooks for this edge. */
+	listWebhooks(): Promise<Array<Record<string, unknown>>>;
+	private startHeartbeat;
+	private stopHeartbeat;
+	private sendHeartbeat;
+	private extractPeerMethod;
+	private extractBroadcastPeerMethod;
+	private registerPeerService;
+	private getAuthHeaders;
+}
+declare class MethodBuilder {
+	private methodDescriptor;
+	private parent;
+	constructor(parent: ServiceBuilder, name: string, description?: string);
+	/**
+	 * Add AI context to this method.
+	 */
+	withAI(aiContext: MethodAIContext): MethodBuilder;
+	/**
+	 * Add another method to the service (returns to service builder context).
+	 */
+	method(name: string, description?: string): MethodBuilder;
+	/**
+	 * Build the final ServiceDescriptor.
+	 */
+	build(): ServiceDescriptor;
+	/**
+	 * Create a ServiceHandler from the builder with the given implementation.
+	 */
+	toHandler(impl: Record<string, (data: unknown) => Promise<unknown>>): ServiceHandler & {
+		_descriptor: ServiceDescriptor;
+	};
+	/**
+	 * Internal: Get the method descriptor.
+	 */
+	_getDescriptor(): MethodDescriptor;
+}
+/**
+ * ServiceBuilder provides a fluent API for building ServiceDescriptor with AI context.
+ *
+ * @example
+ * ```typescript
+ * const builder = new ServiceBuilder('SensorService', '1.0.0')
+ *   .description('Manages sensor data')
+ *   .withAI({
+ *     overview: 'Service for reading and managing sensor data',
+ *     capabilities: ['read temperature', 'set thresholds'],
+ *   })
+ *   .method('ReadTemperature', 'Reads current temperature')
+ *   .withAI({ when_to_use: 'When you need current sensor readings' })
+ *   .withExample('typescript', 'await sensor.readTemperature()', 'Basic usage')
+ *   .method('SetThreshold')
+ *   .withAI({ when_to_use: 'When you need to configure alerts' });
+ *
+ * const handler = builder.toHandler({
+ *   ReadTemperature: async () => ({ value: 23.5 }),
+ *   SetThreshold: async (data) => ({ success: true }),
+ * });
+ *
+ * await edge.exposeService(handler);
+ * ```
+ */
+export declare class ServiceBuilder {
+	private descriptor;
+	private methodBuilders;
+	private currentMethodBuilder;
+	constructor(name: string, version: string);
+	/**
+	 * Set the service description.
+	 */
+	description(desc: string): ServiceBuilder;
+	/**
+	 * Add AI context to the service.
+	 */
+	withAI(aiContext: ServiceAIContext): ServiceBuilder;
+	/**
+	 * Add a related service.
+	 */
+	relatedService(serviceName: string): ServiceBuilder;
+	/**
+	 * Add a method to the service. Returns a MethodBuilder for fluent chaining.
+	 */
+	method(name: string, description?: string): MethodBuilder;
+	/**
+	 * Build the final ServiceDescriptor.
+	 */
+	build(): ServiceDescriptor;
+	/**
+	 * Create a ServiceHandler from the builder with the given implementation.
+	 *
+	 * @param impl - Object mapping method names to handler functions
+	 * @returns A ServiceHandler that can be passed to EdgeClient.exposeService()
+	 */
+	toHandler(impl: Record<string, (data: unknown) => Promise<unknown>>): ServiceHandler & {
+		_descriptor: ServiceDescriptor;
+	};
+}
+/** Type alias for the edge connection passed to onConnected/onError callbacks */
+export type EdgeConnection = EdgeClient;
+/**
+ * Options for createEdgeWorker.
+ */
+export interface EdgeWorkerOptions {
+	/** Services to expose. Required, at least one. */
+	services: ServiceHandler[];
+	/** API key. Defaults to process.env.DINK_EDGE_KEY || process.env.DINK_API_KEY */
+	apiKey?: string;
+	/** Server URL. Optional if using new key format with embedded URL. Defaults to process.env.DINK_SERVER_URL */
+	serverUrl?: string;
+	/** Display name for the edge. Defaults to process.env.EDGE_NAME */
+	edgeName?: string;
+	/** Labels for edge discovery */
+	labels?: Record<string, string>;
+	/** Heartbeat interval in ms (default: 30000) */
+	heartbeatInterval?: number;
+	/** Whether to register SIGINT/SIGTERM handlers for graceful shutdown (default: true) */
+	gracefulShutdown?: boolean;
+	/** Callback when connected */
+	onConnected?: (edge: EdgeClient) => void;
+	/** Callback when disconnected */
+	onDisconnected?: () => void;
+	/** Callback on error */
+	onError?: (error: Error) => void;
+}
+/**
+ * Handle returned by createEdgeWorker for lifecycle control.
+ */
+export interface EdgeWorkerHandle {
+	/** The underlying EdgeClient instance */
+	client: EdgeClient;
+	/** Gracefully shut down the worker */
+	shutdown: () => Promise<void>;
+	/** Promise that resolves when the worker shuts down */
+	done: Promise<void>;
+}
+/**
+ * Create and start an edge worker with minimal configuration.
+ *
+ * Handles credential resolution from environment, connection, service exposure,
+ * signal handling, and graceful shutdown automatically.
+ *
+ * @example
+ * ```typescript
+ * import { createEdgeWorker } from '@fatagnus/dink-sdk/edge'
+ * import { SensorServiceHandler } from './generated/sensorservice.handler.js'
+ * import { SensorServiceImpl } from './sensor-impl.js'
+ *
+ * await createEdgeWorker({
+ *   services: [new SensorServiceHandler(new SensorServiceImpl())],
+ *   labels: { region: 'us-east', type: 'sensor' },
+ * })
+ * ```
+ */
+export declare function createEdgeWorker(options: EdgeWorkerOptions): Promise<EdgeWorkerHandle>;
+
+export {};

package/dist/edge/service-builder.d.ts

@@ -91,4 +91,3 @@ export declare class ServiceBuilder {
     };
 }
 export {};
-//# sourceMappingURL=service-builder.d.ts.map

package/dist/edge/worker.d.ts

@@ -57,4 +57,3 @@ export interface EdgeWorkerHandle {
  * ```
  */
 export declare function createEdgeWorker(options: EdgeWorkerOptions): Promise<EdgeWorkerHandle>;
-//# sourceMappingURL=worker.d.ts.map

package/dist/env/index.d.ts

@@ -1,25 +1,27 @@
+// Generated by dts-bundle-generator v9.5.1
+
 /**
  * Credentials loaded from a .dink/ environment or env vars.
  */
 export interface DinkEnv {
-    name: string;
-    server: string;
-    apiKey: string;
-    appId: string;
-    syncKey: string;
+	name: string;
+	server: string;
+	apiKey: string;
+	appId: string;
+	syncKey: string;
 }
 /**
  * Options for loadDinkEnv.
  */
 export interface LoadOptions {
-    app?: string;
+	app?: string;
 }
 /**
  * Error thrown when environment resolution fails.
  */
 export declare class DinkEnvError extends Error {
-    readonly code: 'NO_ENVIRONMENT' | 'NOT_FOUND';
-    constructor(message: string, code: 'NO_ENVIRONMENT' | 'NOT_FOUND');
+	readonly code: "NO_ENVIRONMENT" | "NOT_FOUND";
+	constructor(message: string, code: "NO_ENVIRONMENT" | "NOT_FOUND");
 }
 /**
  * Load Dink credentials.
@@ -38,4 +40,5 @@ export declare class DinkEnvError extends Error {
  * 5. empty string
  */
 export declare function loadDinkEnv(name?: string, options?: LoadOptions): Promise<DinkEnv>;
-//# sourceMappingURL=index.d.ts.map
+
+export {};

package/dist/errors.d.ts

@@ -50,4 +50,3 @@ export declare class ConfigError extends DinkError {
 export declare class WebhookError extends DinkError {
     constructor(message: string, code?: string);
 }
-//# sourceMappingURL=errors.d.ts.map