@fatagnus/dink-sdk 2.23.1 → 2.24.1

package/dist/center/index.d.ts

@@ -1,2 +1,578 @@
-export { CenterClient, type CenterChannel } from './client.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 CenterClient
+ */
+export interface CenterConfig {
+	/** dinkd server URL (e.g., "nats://localhost:4222") */
+	serverUrl: string;
+	/** App API key for authentication */
+	apiKey?: string;
+	/** App ID (optional, defaults to 'platform') */
+	appId?: string;
+	/** 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;
+}
+/**
+ * Type of API key
+ */
+export type KeyType = "edge" | "center" | "client" | "admin" | "app_master" | "sync_key";
+/**
+ * Status of an API key
+ */
+export type KeyStatus = "active" | "expired" | "revoked" | "disabled";
+/**
+ * Metadata about an API key
+ */
+export interface KeyMetadata {
+	/** Unique key identifier */
+	id: string;
+	/** App ID this key belongs to */
+	appId: string;
+	/** Display name of the key */
+	name: string;
+	/** Type of the key */
+	type: KeyType;
+	/** Edge ID (for edge keys) */
+	edgeId?: string;
+	/** Scopes granted to this key */
+	scopes: string[];
+	/** Resource restrictions */
+	resources?: {
+		services?: string[];
+		streams?: string[];
+		kvBuckets?: string[];
+		events?: string[];
+	};
+	/** Labels attached to the key */
+	labels?: Record<string, string>;
+	/** Current status of the key */
+	status: KeyStatus;
+	/** When the key was created */
+	createdAt: Date;
+	/** When the key expires (if set) */
+	expiresAt?: Date;
+	/** When the key was last used */
+	lastUsedAt?: Date;
+	/** When the key was revoked (if revoked) */
+	revokedAt?: Date;
+	/** Reason for revocation (if revoked) */
+	revokeReason?: string;
+	/** Groups for peer communication */
+	groups?: string[];
+}
+/**
+ * Options for creating an API key
+ */
+export interface CreateKeyOptions {
+	/** Display name for the key */
+	name: string;
+	/** Type of key to create */
+	type: KeyType;
+	/** Edge ID (optional for edge keys, auto-generated if not provided) */
+	edgeId?: string;
+	/** Scopes to grant (optional, defaults based on type) */
+	scopes?: string[];
+	/** Scope bundle to use (e.g., 'bundle:edge') */
+	scopeBundle?: string;
+	/** Expiration time (e.g., '24h', '7d', '30d') */
+	expiresIn?: string;
+	/** Labels to attach to the key */
+	labels?: Record<string, string>;
+	/** Groups for peer-to-peer communication */
+	groups?: string[];
+}
+/**
+ * Result from creating an API key
+ */
+export interface CreateKeyResult {
+	/** Key metadata */
+	key: KeyMetadata;
+	/** The actual API key (only shown once!) */
+	apiKey: string;
+}
+/**
+ * Options for listing keys
+ */
+export interface ListKeysOptions {
+	/** Filter by key type */
+	type?: KeyType;
+	/** Filter by labels */
+	labels?: Record<string, string>;
+}
+/**
+ * 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[];
+}
+/** Bidirectional raw byte channel (center-to-edge). */
+export interface CenterChannel {
+	/** Unique channel identifier */
+	readonly id: string;
+	/** Send raw bytes to the edge. Returns false if backpressure is active. */
+	write(data: Uint8Array): boolean;
+	/** Register handler for incoming raw bytes from edge */
+	onData(handler: (data: Uint8Array) => void): void;
+	/** Close the channel */
+	close(): void;
+	/** Called when the channel closes. 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 declare class CenterClient implements ServiceCaller {
+	private config;
+	private nc;
+	private appId;
+	private connectionState;
+	private lastLatencyMs;
+	private lastPingAt;
+	private latencyHistory;
+	private messagesSent;
+	private messagesReceived;
+	private statsStartedAt;
+	private qualityCallbacks;
+	private qualityConfig;
+	private pingTimer;
+	constructor(config: CenterConfig);
+	connect(): Promise<void>;
+	close(): Promise<void>;
+	isConnected(): boolean;
+	/**
+	 * 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;
+	discoverEdges(opts?: DiscoverOptions): Promise<EdgeInfo[]>;
+	listEdges(): Promise<EdgeInfo[]>;
+	call<Req, Resp>(edgeId: string, service: string, method: string, req: Req, opts?: CallOptions): Promise<Resp>;
+	subscribe<Req, Resp>(edgeId: string, service: string, method: string, req: Req, handler: (resp: Resp) => void): Promise<Subscription>;
+	/**
+	 * Open a bidirectional raw byte channel to an edge service.
+	 */
+	openChannel(edgeId: string, service: string, method: string, request?: unknown): Promise<CenterChannel>;
+	/**
+	 * Call an edge RPC method and receive a streaming response.
+	 * Returns an async iterable that yields response chunks.
+	 */
+	callEdgeRpcStream<Req>(edgeId: string, service: string, method: string, req: Req, opts?: CallOptions): AsyncGenerator<Uint8Array, void, undefined>;
+	private delay;
+	private getAuthHeaders;
+	/**
+	 * Register a webhook endpoint for an edge service.
+	 */
+	registerWebhook(opts: {
+		edgeId: string;
+		service: string;
+		method: string;
+		secret?: string;
+		secretMode?: string;
+		description?: string;
+	}): Promise<Record<string, unknown>>;
+	/**
+	 * List webhook registrations.
+	 * @param filter - Optional filter by edgeId
+	 */
+	listWebhooks(filter?: {
+		edgeId?: string;
+	}): Promise<Array<Record<string, unknown>>>;
+	/**
+	 * Delete a webhook registration.
+	 * @param webhookId - The webhook ID to delete
+	 */
+	deleteWebhook(webhookId: string): Promise<void>;
+	/**
+	 * Get a specific webhook by ID.
+	 * @param webhookId - The webhook ID
+	 */
+	getWebhook(webhookId: string): Promise<Record<string, unknown>>;
+	/**
+	 * Describe a service by name, returning its ServiceDescriptor.
+	 * @param serviceName - The name or ID of the service to describe
+	 * @returns Promise resolving to the ServiceDescriptor
+	 */
+	describeService(serviceName: string): Promise<ServiceDescriptor>;
+	/**
+	 * Describe a specific method of a service, returning its MethodDescriptor.
+	 * @param serviceName - The name or ID of the service
+	 * @param methodName - The name of the method to describe
+	 * @returns Promise resolving to the MethodDescriptor
+	 */
+	describeMethod(serviceName: string, methodName: string): Promise<MethodDescriptor>;
+	/**
+	 * Get LLM-friendly context (llm.txt format) for specified services.
+	 * @param serviceNames - A single service name or array of service names
+	 * @returns Promise resolving to llm.txt formatted string
+	 */
+	getLLMContext(serviceNames: string | string[]): Promise<string>;
+	/**
+	 * Get LLM-friendly context (llm.txt format) for all registered services.
+	 * @returns Promise resolving to llm.txt formatted string
+	 */
+	getAllLLMContext(): Promise<string>;
+	/**
+	 * List all services with their full ServiceDescriptors.
+	 * @returns Promise resolving to array of ServiceDescriptors
+	 */
+	listServicesWithDescriptions(): Promise<ServiceDescriptor[]>;
+	/**
+	 * Internal helper to list services from the API.
+	 */
+	private listServicesInternal;
+	/**
+	 * Internal helper to get descriptors for a list of services.
+	 */
+	private getDescriptorsForServices;
+	/**
+	 * Create a new API key.
+	 * @param options - Key creation options
+	 * @returns Promise resolving to the created key metadata and API key string
+	 * @throws Error if key creation fails
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await client.createKey({
+	 *   name: 'my-edge-agent',
+	 *   type: 'edge',
+	 * });
+	 * console.log('API Key (save this!):', result.apiKey);
+	 * console.log('Edge ID:', result.key.edgeId);
+	 * ```
+	 */
+	createKey(options: CreateKeyOptions): Promise<CreateKeyResult>;
+	/**
+	 * List API keys with optional filtering.
+	 * @param options - Optional filter options
+	 * @returns Promise resolving to array of key metadata
+	 *
+	 * @example
+	 * ```typescript
+	 * // List all edge keys
+	 * const keys = await client.listKeys({ type: 'edge' });
+	 * for (const key of keys) {
+	 *   console.log(`${key.name}: ${key.status}`);
+	 * }
+	 * ```
+	 */
+	listKeys(options?: ListKeysOptions): Promise<KeyMetadata[]>;
+	/**
+	 * Get details of a specific key.
+	 * @param keyId - The key ID to retrieve
+	 * @returns Promise resolving to key metadata
+	 *
+	 * @example
+	 * ```typescript
+	 * const key = await client.getKey('key-123');
+	 * console.log(`Key status: ${key.status}`);
+	 * ```
+	 */
+	getKey(keyId: string): Promise<KeyMetadata>;
+	/**
+	 * Revoke an API key.
+	 * @param keyId - The key ID to revoke
+	 * @param reason - Optional reason for revocation
+	 *
+	 * @example
+	 * ```typescript
+	 * await client.revokeKey('key-123', 'No longer needed');
+	 * ```
+	 */
+	revokeKey(keyId: string, reason?: string): Promise<void>;
+	/**
+	 * Delete a revoked API key permanently.
+	 * Only revoked keys can be deleted - active keys must be revoked first.
+	 * @param keyId - The key ID to delete
+	 *
+	 * @example
+	 * ```typescript
+	 * await client.deleteKey('key-123');
+	 * ```
+	 */
+	deleteKey(keyId: string): Promise<void>;
+	/**
+	 * Rotate an API key (revokes old key and creates new one).
+	 * @param keyId - The key ID to rotate
+	 * @returns Promise resolving to the new key metadata and API key string
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await client.rotateKey('key-123');
+	 * console.log('New API Key:', result.apiKey);
+	 * ```
+	 */
+	rotateKey(keyId: string): Promise<CreateKeyResult>;
+	/**
+	 * Expose a center service into a group namespace.
+	 * Edges in the group can call this service.
+	 * Subscribes on: center.{appId}.group.{groupId}.services.{name}.>
+	 */
+	exposeToGroup(groupId: string, handler: ServiceHandler): Promise<Subscription>;
+	/**
+	 * Call a specific edge's service within a group.
+	 * Publishes to: edge.{appId}.group.{groupId}.{edgeId}.services.{service}.{method}
+	 */
+	callGroup<Req, Resp>(groupId: string, edgeId: string, service: string, method: string, req: Req, opts?: CallOptions): Promise<Resp>;
+	/**
+	 * Scatter call to all edges in a group.
+	 * Discovers edges in the group, then calls each via directed subject in parallel.
+	 * Returns a map of edgeID → response data.
+	 */
+	scatterGroup<Req, Resp>(groupId: string, service: string, method: string, req: Req, opts?: CallOptions): Promise<Record<string, Resp>>;
+	/**
+	 * Helper to parse key metadata from API response.
+	 */
+	private parseKeyMetadata;
+	/**
+	 * Internal helper to format ServiceDescriptors as llm.txt.
+	 */
+	private formatAsLLMTxt;
+	/**
+	 * Call an RPC method on any edge exposing the given service.
+	 * Discovers an available edge first, then routes the call.
+	 */
+	callServiceRpc<Req, Resp>(service: string, method: string, req: Req, opts?: CallOptions & {
+		labels?: Record<string, string>;
+	}): Promise<Resp>;
+	/**
+	 * List all services available in the mesh.
+	 */
+	listServices(): Promise<Array<{
+		name: string;
+		version?: string;
+		edgeCount: number;
+	}>>;
+}
+
+export {};

package/dist/edge/client.d.ts

@@ -162,4 +162,3 @@ export declare class EdgeClient {
     private registerPeerService;
     private getAuthHeaders;
 }
-//# sourceMappingURL=client.d.ts.map

package/dist/edge/client.js

@@ -413,6 +413,7 @@ export class EdgeClient {
         const nc = this.nc;
         let inputSub = null;
         let cancelSub = null;
+        let ctrlSub = null;
         let open = true;
         try {
             // Parse the channel initiation message
@@ -424,6 +425,16 @@ export class EdgeClient {
             if (channelPayload && typeof channelPayload === 'object' && 'payload' in channelPayload) {
                 channelPayload = channelPayload.payload || {};
             }
+            // Generate channel ID from output subject
+            const channelId = 'ch_' + (outputSubject.split('.').pop() || outputSubject);
+            // Control message handlers
+            const controlHandlers = [];
+            // Backpressure tracking
+            let _bufferedAmount = 0;
+            const drainHandlers = [];
+            // Closed promise
+            let resolveClosed;
+            const closedPromise = new Promise((resolve) => { resolveClosed = resolve; });
             const dataHandlers = [];
             const closeHandlers = [];
             const cleanup = (reason) => {
@@ -432,6 +443,8 @@ export class EdgeClient {
                 open = false;
                 inputSub?.unsubscribe();
                 cancelSub?.unsubscribe();
+                ctrlSub?.unsubscribe();
+                resolveClosed();
                 for (const h of closeHandlers) {
                     try {
                         h(reason);
@@ -460,16 +473,50 @@ export class EdgeClient {
                     cleanup('cancelled by client');
                 },
             });
+            // Subscribe to control messages from browser
+            try {
+                ctrlSub = nc.subscribe(inputSubject + '.ctrl', {
+                    callback: (_err, msg) => {
+                        if (!open)
+                            return;
+                        try {
+                            const parsed = JSON.parse(sc.decode(msg.data));
+                            for (const h of controlHandlers) {
+                                try {
+                                    h(parsed);
+                                }
+                                catch { /* ignore */ }
+                            }
+                        }
+                        catch { /* ignore parse errors */ }
+                    },
+                });
+            }
+            catch { /* ctrl subscription is optional */ }
             // ACK the channel request
             if (msg.reply) {
-                msg.respond(sc.encode(JSON.stringify({ status: 'channel', cancelSubject })));
+                msg.respond(sc.encode(JSON.stringify({ status: 'channel', cancelSubject, channelId })));
             }
             // Build the EdgeChannel object
             const channel = {
+                get id() { return channelId; },
                 write(data) {
                     if (!open)
-                        return;
+                        return false;
                     nc.publish(outputSubject, data);
+                    _bufferedAmount += data.byteLength;
+                    queueMicrotask(() => {
+                        _bufferedAmount = Math.max(0, _bufferedAmount - data.byteLength);
+                        if (_bufferedAmount === 0) {
+                            for (const h of drainHandlers) {
+                                try {
+                                    h();
+                                }
+                                catch { /* ignore */ }
+                            }
+                        }
+                    });
+                    return true;
                 },
                 onData(handler) {
                     dataHandlers.push(handler);
@@ -483,9 +530,18 @@ export class EdgeClient {
                 onClose(handler) {
                     closeHandlers.push(handler);
                 },
-                get isOpen() {
-                    return open;
+                sendControl(msg) {
+                    if (!open)
+                        return;
+                    nc.publish(outputSubject + '.ctrl', sc.encode(JSON.stringify(msg)));
+                },
+                onControl(handler) {
+                    controlHandlers.push(handler);
                 },
+                get isOpen() { return open; },
+                get closed() { return closedPromise; },
+                get bufferedAmount() { return _bufferedAmount; },
+                onDrain(handler) { drainHandlers.push(handler); },
             };
             // Call the handler — it may hold the channel open as long as it needs
             await handler.handleChannel(method, channel, channelPayload);
@@ -503,6 +559,7 @@ export class EdgeClient {
         finally {
             inputSub?.unsubscribe();
             cancelSub?.unsubscribe();
+            ctrlSub?.unsubscribe();
         }
     }
     async unexposeService(name) {