@rstmdb/client 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,888 @@
1
+ import { EventEmitter } from 'events';
2
+
3
+ /**
4
+ * A stream event from a watch subscription.
5
+ */
6
+ interface StreamEvent {
7
+ /** Subscription ID */
8
+ subscriptionId: string;
9
+ /** Instance ID */
10
+ instanceId: string;
11
+ /** Machine name */
12
+ machine: string;
13
+ /** Machine version */
14
+ version: number;
15
+ /** WAL offset */
16
+ walOffset: bigint;
17
+ /** Source state */
18
+ fromState: string;
19
+ /** Target state */
20
+ toState: string;
21
+ /** Event name */
22
+ event: string;
23
+ /** Event payload */
24
+ payload?: Record<string, unknown>;
25
+ /** Instance context */
26
+ ctx?: Record<string, unknown>;
27
+ }
28
+ /**
29
+ * Options for WATCH_INSTANCE operation.
30
+ */
31
+ interface WatchOptions {
32
+ /** Include context in events. Default: true */
33
+ includeCtx?: boolean;
34
+ /** Replay events from this offset */
35
+ fromOffset?: bigint;
36
+ }
37
+ /**
38
+ * Options for WATCH_ALL operation.
39
+ */
40
+ interface WatchAllOptions extends WatchOptions {
41
+ /** Filter by machine names */
42
+ machines?: string[];
43
+ /** Filter by source states */
44
+ fromStates?: string[];
45
+ /** Filter by target states */
46
+ toStates?: string[];
47
+ /** Filter by event names */
48
+ events?: string[];
49
+ }
50
+ /**
51
+ * A subscription to watch events.
52
+ */
53
+ interface Subscription {
54
+ /** Subscription ID */
55
+ readonly subscriptionId: string;
56
+ /** AsyncIterator for for-await-of loops */
57
+ [Symbol.asyncIterator](): AsyncIterator<StreamEvent>;
58
+ /** Register event listener */
59
+ on(event: 'event', listener: (event: StreamEvent) => void): this;
60
+ on(event: 'error', listener: (error: Error) => void): this;
61
+ on(event: 'end', listener: () => void): this;
62
+ /** Remove event listener */
63
+ off(event: 'event', listener: (event: StreamEvent) => void): this;
64
+ off(event: 'error', listener: (error: Error) => void): this;
65
+ off(event: 'end', listener: () => void): this;
66
+ /** Cancel the subscription */
67
+ unsubscribe(): Promise<void>;
68
+ }
69
+
70
+ /**
71
+ * TLS configuration options for secure connections.
72
+ */
73
+ interface TlsConfig {
74
+ /** CA certificate(s) for server verification */
75
+ ca?: string | Buffer | string[];
76
+ /** Whether to reject unauthorized certificates. Default: true */
77
+ rejectUnauthorized?: boolean;
78
+ /** Client certificate for mTLS */
79
+ cert?: string | Buffer;
80
+ /** Client private key for mTLS */
81
+ key?: string | Buffer;
82
+ /** Server name for SNI */
83
+ servername?: string;
84
+ }
85
+ /**
86
+ * Client configuration options.
87
+ */
88
+ interface ClientConfig {
89
+ /** Server hostname */
90
+ host: string;
91
+ /** Server port. Default: 7401 */
92
+ port?: number;
93
+ /** Connection timeout in milliseconds. Default: 10000 */
94
+ connectTimeout?: number;
95
+ /** Request timeout in milliseconds. Default: 30000 */
96
+ requestTimeout?: number;
97
+ /** Bearer token for authentication */
98
+ authToken?: string;
99
+ /** TLS configuration. true = use TLS with system CA */
100
+ tls?: TlsConfig | boolean;
101
+ /** Enable automatic reconnection. Default: true */
102
+ reconnect?: boolean;
103
+ /** Reconnection interval in milliseconds. Default: 1000 */
104
+ reconnectInterval?: number;
105
+ /** Maximum reconnection attempts. Default: 10 */
106
+ reconnectMaxAttempts?: number;
107
+ /** Client name sent in HELLO */
108
+ clientName?: string;
109
+ }
110
+ /**
111
+ * Resolved configuration with all defaults applied.
112
+ */
113
+ interface ResolvedConfig {
114
+ host: string;
115
+ port: number;
116
+ connectTimeout: number;
117
+ requestTimeout: number;
118
+ authToken?: string;
119
+ tls?: TlsConfig;
120
+ reconnect: boolean;
121
+ reconnectInterval: number;
122
+ reconnectMaxAttempts: number;
123
+ clientName?: string;
124
+ }
125
+ /**
126
+ * Default configuration values.
127
+ */
128
+ declare const DEFAULT_CONFIG: {
129
+ readonly port: 7401;
130
+ readonly connectTimeout: 10000;
131
+ readonly requestTimeout: 30000;
132
+ readonly reconnect: true;
133
+ readonly reconnectInterval: 1000;
134
+ readonly reconnectMaxAttempts: 10;
135
+ };
136
+ /**
137
+ * Builder for creating client configurations with a fluent API.
138
+ *
139
+ * @example
140
+ * ```typescript
141
+ * const config = ClientOptions.create('localhost')
142
+ * .port(7401)
143
+ * .auth('my-token')
144
+ * .tls({ rejectUnauthorized: true })
145
+ * .timeout({ connect: 5000, request: 15000 })
146
+ * .reconnect({ enabled: true, maxAttempts: 5 })
147
+ * .build();
148
+ *
149
+ * const client = new Client(config);
150
+ * ```
151
+ */
152
+ declare class ClientOptions {
153
+ private config;
154
+ private constructor();
155
+ /**
156
+ * Create a new options builder with the given host.
157
+ */
158
+ static create(host: string): ClientOptions;
159
+ /**
160
+ * Set the server port.
161
+ * @default 7401
162
+ */
163
+ port(port: number): this;
164
+ /**
165
+ * Set the authentication token.
166
+ */
167
+ auth(token: string): this;
168
+ /**
169
+ * Configure TLS settings.
170
+ *
171
+ * @param config - TLS configuration, or `true` to enable with system CA
172
+ *
173
+ * @example
174
+ * ```typescript
175
+ * // Enable TLS with system CA
176
+ * options.tls(true)
177
+ *
178
+ * // Custom CA certificate
179
+ * options.tls({ ca: fs.readFileSync('ca.pem') })
180
+ *
181
+ * // mTLS with client certificate
182
+ * options.tls({
183
+ * ca: fs.readFileSync('ca.pem'),
184
+ * cert: fs.readFileSync('client.pem'),
185
+ * key: fs.readFileSync('client-key.pem'),
186
+ * })
187
+ * ```
188
+ */
189
+ tls(config: TlsConfig | boolean): this;
190
+ /**
191
+ * Set timeout values.
192
+ */
193
+ timeout(options: {
194
+ connect?: number;
195
+ request?: number;
196
+ }): this;
197
+ /**
198
+ * Configure reconnection behavior.
199
+ */
200
+ reconnect(options: {
201
+ enabled?: boolean;
202
+ interval?: number;
203
+ maxAttempts?: number;
204
+ }): this;
205
+ /**
206
+ * Set the client name (sent in HELLO handshake).
207
+ */
208
+ clientName(name: string): this;
209
+ /**
210
+ * Build the configuration object.
211
+ */
212
+ build(): ClientConfig;
213
+ }
214
+
215
+ /**
216
+ * A state machine transition definition.
217
+ */
218
+ interface Transition {
219
+ /** Source state(s) */
220
+ from: string | string[];
221
+ /** Event that triggers the transition */
222
+ event: string;
223
+ /** Target state */
224
+ to: string;
225
+ /** Optional guard expression */
226
+ guard?: string;
227
+ }
228
+ /**
229
+ * A state machine definition.
230
+ */
231
+ interface MachineDefinition {
232
+ /** List of valid states */
233
+ states: string[];
234
+ /** Initial state for new instances */
235
+ initial: string;
236
+ /** Transition definitions */
237
+ transitions: Transition[];
238
+ /** Optional metadata */
239
+ meta?: Record<string, unknown>;
240
+ }
241
+ /**
242
+ * Result of PUT_MACHINE operation.
243
+ */
244
+ interface PutMachineResult {
245
+ /** Machine name */
246
+ machine: string;
247
+ /** Machine version */
248
+ version: number;
249
+ /** Checksum of stored definition */
250
+ storedChecksum: string;
251
+ /** Whether the machine was newly created */
252
+ created: boolean;
253
+ }
254
+ /**
255
+ * Result of GET_MACHINE operation.
256
+ */
257
+ interface GetMachineResult {
258
+ /** Machine definition */
259
+ definition: MachineDefinition;
260
+ /** Definition checksum */
261
+ checksum: string;
262
+ }
263
+ /**
264
+ * A machine entry in LIST_MACHINES result.
265
+ */
266
+ interface MachineListItem {
267
+ /** Machine name */
268
+ machine: string;
269
+ /** Available versions */
270
+ versions: number[];
271
+ }
272
+ /**
273
+ * Options for LIST_MACHINES operation.
274
+ */
275
+ interface ListMachinesOptions {
276
+ /** Pagination cursor */
277
+ cursor?: string;
278
+ /** Maximum items to return */
279
+ limit?: number;
280
+ }
281
+ /**
282
+ * Result of LIST_MACHINES operation.
283
+ */
284
+ interface ListMachinesResult {
285
+ /** List of machines */
286
+ items: MachineListItem[];
287
+ /** Cursor for next page, if more results exist */
288
+ nextCursor?: string;
289
+ }
290
+
291
+ /**
292
+ * Options for CREATE_INSTANCE operation.
293
+ */
294
+ interface CreateInstanceOptions {
295
+ /** Custom instance ID (server generates if omitted) */
296
+ instanceId?: string;
297
+ /** Initial context data */
298
+ initialCtx?: Record<string, unknown>;
299
+ /** Idempotency key for deduplication */
300
+ idempotencyKey?: string;
301
+ }
302
+ /**
303
+ * Result of CREATE_INSTANCE operation.
304
+ */
305
+ interface CreateInstanceResult {
306
+ /** Generated or provided instance ID */
307
+ instanceId: string;
308
+ /** Initial state */
309
+ state: string;
310
+ /** WAL offset of the creation */
311
+ walOffset: bigint;
312
+ }
313
+ /**
314
+ * Result of GET_INSTANCE operation.
315
+ */
316
+ interface GetInstanceResult {
317
+ /** Machine name */
318
+ machine: string;
319
+ /** Machine version */
320
+ version: number;
321
+ /** Current state */
322
+ state: string;
323
+ /** Current context */
324
+ ctx: Record<string, unknown>;
325
+ /** Last applied event ID */
326
+ lastEventId?: string;
327
+ /** Last WAL offset */
328
+ lastWalOffset: bigint;
329
+ }
330
+ /**
331
+ * Options for DELETE_INSTANCE operation.
332
+ */
333
+ interface DeleteInstanceOptions {
334
+ /** Idempotency key for deduplication */
335
+ idempotencyKey?: string;
336
+ }
337
+
338
+ /**
339
+ * Error codes used by the rstmdb client.
340
+ */
341
+ declare enum ErrorCode {
342
+ UNSUPPORTED_PROTOCOL = "UNSUPPORTED_PROTOCOL",
343
+ BAD_REQUEST = "BAD_REQUEST",
344
+ UNAUTHORIZED = "UNAUTHORIZED",
345
+ AUTH_FAILED = "AUTH_FAILED",
346
+ NOT_FOUND = "NOT_FOUND",
347
+ MACHINE_NOT_FOUND = "MACHINE_NOT_FOUND",
348
+ MACHINE_VERSION_EXISTS = "MACHINE_VERSION_EXISTS",
349
+ INSTANCE_NOT_FOUND = "INSTANCE_NOT_FOUND",
350
+ INSTANCE_EXISTS = "INSTANCE_EXISTS",
351
+ INVALID_TRANSITION = "INVALID_TRANSITION",
352
+ GUARD_FAILED = "GUARD_FAILED",
353
+ CONFLICT = "CONFLICT",
354
+ WAL_IO_ERROR = "WAL_IO_ERROR",
355
+ INTERNAL_ERROR = "INTERNAL_ERROR",
356
+ RATE_LIMITED = "RATE_LIMITED",
357
+ CONNECTION_FAILED = "CONNECTION_FAILED",
358
+ CONNECTION_CLOSED = "CONNECTION_CLOSED",
359
+ TIMEOUT = "TIMEOUT"
360
+ }
361
+
362
+ /**
363
+ * Base error class for all rstmdb errors.
364
+ */
365
+ declare class RstmdbError extends Error {
366
+ /** Error code */
367
+ readonly code: ErrorCode;
368
+ /** Whether the operation can be retried */
369
+ readonly retryable: boolean;
370
+ /** Additional error details */
371
+ readonly details?: Record<string, unknown>;
372
+ constructor(message: string, code: ErrorCode, options?: {
373
+ retryable?: boolean;
374
+ details?: Record<string, unknown>;
375
+ cause?: Error;
376
+ });
377
+ /**
378
+ * Create an error from a server response.
379
+ */
380
+ static fromResponse(response: {
381
+ code: string;
382
+ message: string;
383
+ details?: Record<string, unknown>;
384
+ }): RstmdbError;
385
+ }
386
+
387
+ /**
388
+ * Options for APPLY_EVENT operation.
389
+ */
390
+ interface ApplyEventOptions {
391
+ /** Event payload data */
392
+ payload?: Record<string, unknown>;
393
+ /** Expected current state (optimistic concurrency) */
394
+ expectedState?: string;
395
+ /** Expected WAL offset (stronger concurrency check) */
396
+ expectedWalOffset?: bigint;
397
+ /** Custom event ID */
398
+ eventId?: string;
399
+ /** Idempotency key for deduplication */
400
+ idempotencyKey?: string;
401
+ }
402
+ /**
403
+ * Result of APPLY_EVENT operation.
404
+ */
405
+ interface ApplyEventResult {
406
+ /** State before transition */
407
+ fromState: string;
408
+ /** State after transition */
409
+ toState: string;
410
+ /** Updated context (if changed) */
411
+ ctx?: Record<string, unknown>;
412
+ /** WAL offset of the event */
413
+ walOffset: bigint;
414
+ /** Whether the event was applied */
415
+ applied: boolean;
416
+ /** Event ID */
417
+ eventId?: string;
418
+ }
419
+ /**
420
+ * A batch operation definition.
421
+ */
422
+ interface BatchOperation {
423
+ /** Operation type */
424
+ op: 'CREATE_INSTANCE' | 'APPLY_EVENT' | 'DELETE_INSTANCE';
425
+ /** Operation parameters */
426
+ params: Record<string, unknown>;
427
+ }
428
+ /**
429
+ * Options for BATCH operation.
430
+ */
431
+ interface BatchOptions {
432
+ /** Execution mode */
433
+ mode: 'atomic' | 'best_effort';
434
+ }
435
+ /**
436
+ * A single result within a batch.
437
+ */
438
+ interface BatchResultItem {
439
+ /** Result status */
440
+ status: 'ok' | 'error';
441
+ /** Operation result (if successful) */
442
+ result?: unknown;
443
+ /** Error (if failed) */
444
+ error?: RstmdbError;
445
+ }
446
+ /**
447
+ * Result of BATCH operation.
448
+ */
449
+ interface BatchResult {
450
+ /** Individual operation results */
451
+ results: BatchResultItem[];
452
+ /** WAL offset (for atomic batches) */
453
+ walOffset?: bigint;
454
+ }
455
+ /**
456
+ * Server information from INFO operation.
457
+ */
458
+ interface ServerInfo {
459
+ /** Server name */
460
+ serverName: string;
461
+ /** Server version */
462
+ serverVersion: string;
463
+ /** Protocol version */
464
+ protocolVersion: number;
465
+ /** Maximum payload size in bytes */
466
+ maxPayloadBytes?: number;
467
+ /** Maximum batch operations */
468
+ maxBatchOps?: number;
469
+ /** WAL segment size */
470
+ walSegmentSize?: number;
471
+ /** Whether authentication is required */
472
+ authRequired?: boolean;
473
+ /** Server features */
474
+ features?: string[];
475
+ }
476
+ /**
477
+ * Options for WAL_READ operation.
478
+ */
479
+ interface WalReadOptions {
480
+ /** Maximum entries to read */
481
+ limit?: number;
482
+ }
483
+ /**
484
+ * A WAL entry.
485
+ */
486
+ interface WalEntry {
487
+ /** WAL offset */
488
+ offset: bigint;
489
+ /** Entry type */
490
+ type: string;
491
+ /** Entry data */
492
+ data: Record<string, unknown>;
493
+ /** Timestamp */
494
+ timestamp: number;
495
+ }
496
+ /**
497
+ * Result of WAL_READ operation.
498
+ */
499
+ interface WalReadResult {
500
+ /** WAL entries */
501
+ entries: WalEntry[];
502
+ /** Whether more entries exist */
503
+ hasMore: boolean;
504
+ /** Next offset for pagination */
505
+ nextOffset?: bigint;
506
+ }
507
+ /**
508
+ * Result of SNAPSHOT_INSTANCE operation.
509
+ */
510
+ interface SnapshotResult {
511
+ /** Instance ID */
512
+ instanceId: string;
513
+ /** WAL offset of snapshot */
514
+ walOffset: bigint;
515
+ /** Snapshot size in bytes */
516
+ sizeBytes: number;
517
+ }
518
+ /**
519
+ * Options for COMPACT operation.
520
+ */
521
+ interface CompactOptions {
522
+ /** Force compaction even if not needed */
523
+ force?: boolean;
524
+ }
525
+ /**
526
+ * Result of COMPACT operation.
527
+ */
528
+ interface CompactResult {
529
+ /** Number of snapshots created */
530
+ snapshotsCreated: number;
531
+ /** Number of WAL segments deleted */
532
+ segmentsDeleted: number;
533
+ /** Bytes reclaimed */
534
+ bytesReclaimed: bigint;
535
+ }
536
+
537
+ /**
538
+ * Client events.
539
+ */
540
+ interface ClientEvents {
541
+ connect: () => void;
542
+ disconnect: (error?: Error) => void;
543
+ error: (error: Error) => void;
544
+ reconnect: (attempt: number) => void;
545
+ }
546
+ /**
547
+ * The rstmdb client.
548
+ *
549
+ * @example
550
+ * ```typescript
551
+ * // Simple configuration
552
+ * const client = Client.connect('localhost', 7401);
553
+ *
554
+ * // With authentication
555
+ * const client = Client.connect('localhost', 7401, { auth: 'my-token' });
556
+ *
557
+ * // With full configuration object
558
+ * const client = new Client({
559
+ * host: 'localhost',
560
+ * port: 7401,
561
+ * authToken: 'my-token',
562
+ * tls: true,
563
+ * });
564
+ *
565
+ * // With builder pattern
566
+ * const client = new Client(
567
+ * ClientOptions.create('localhost')
568
+ * .port(7401)
569
+ * .auth('my-token')
570
+ * .tls(true)
571
+ * .timeout({ connect: 5000, request: 15000 })
572
+ * .build()
573
+ * );
574
+ * ```
575
+ */
576
+ declare class Client extends EventEmitter {
577
+ private readonly connection;
578
+ private readonly subscriptions;
579
+ private readonly config;
580
+ constructor(config: ClientConfig);
581
+ /**
582
+ * Create a client and connect to the server.
583
+ *
584
+ * @param host - Server hostname
585
+ * @param port - Server port (default: 7401)
586
+ * @param options - Additional options
587
+ * @returns Connected client instance
588
+ *
589
+ * @example
590
+ * ```typescript
591
+ * const client = await Client.connect('localhost');
592
+ * const client = await Client.connect('localhost', 7401);
593
+ * const client = await Client.connect('localhost', 7401, { auth: 'token' });
594
+ * ```
595
+ */
596
+ static connect(host: string, port?: number, options?: {
597
+ auth?: string;
598
+ tls?: TlsConfig | boolean;
599
+ clientName?: string;
600
+ }): Promise<Client>;
601
+ /**
602
+ * Get the current configuration.
603
+ */
604
+ getConfig(): Readonly<ClientConfig>;
605
+ /**
606
+ * Connect to the server.
607
+ */
608
+ connect(): Promise<void>;
609
+ /**
610
+ * Close the connection.
611
+ */
612
+ close(): Promise<void>;
613
+ /**
614
+ * Check if connected to the server.
615
+ */
616
+ isConnected(): boolean;
617
+ /**
618
+ * Ping the server.
619
+ */
620
+ ping(): Promise<void>;
621
+ /**
622
+ * Get server information.
623
+ */
624
+ info(): Promise<ServerInfo>;
625
+ /**
626
+ * Create or update a state machine definition.
627
+ */
628
+ putMachine(machine: string, version: number, definition: MachineDefinition): Promise<PutMachineResult>;
629
+ /**
630
+ * Get a state machine definition.
631
+ */
632
+ getMachine(machine: string, version: number): Promise<GetMachineResult>;
633
+ /**
634
+ * List all state machines.
635
+ */
636
+ listMachines(options?: ListMachinesOptions): Promise<ListMachinesResult>;
637
+ /**
638
+ * Create a new state machine instance.
639
+ */
640
+ createInstance(machine: string, version: number, options?: CreateInstanceOptions): Promise<CreateInstanceResult>;
641
+ /**
642
+ * Get instance state and context.
643
+ */
644
+ getInstance(instanceId: string): Promise<GetInstanceResult>;
645
+ /**
646
+ * Delete an instance.
647
+ */
648
+ deleteInstance(instanceId: string, options?: DeleteInstanceOptions): Promise<void>;
649
+ /**
650
+ * Apply an event to an instance.
651
+ */
652
+ applyEvent(instanceId: string, event: string, options?: ApplyEventOptions): Promise<ApplyEventResult>;
653
+ /**
654
+ * Execute multiple operations in a batch.
655
+ */
656
+ batch(operations: BatchOperation[], options?: BatchOptions): Promise<BatchResult>;
657
+ /**
658
+ * Read entries from the write-ahead log.
659
+ */
660
+ walRead(fromOffset: bigint, options?: WalReadOptions): Promise<WalReadResult>;
661
+ /**
662
+ * Create a snapshot of an instance.
663
+ */
664
+ snapshotInstance(instanceId: string): Promise<SnapshotResult>;
665
+ /**
666
+ * Trigger WAL compaction.
667
+ */
668
+ compact(options?: CompactOptions): Promise<CompactResult>;
669
+ /**
670
+ * Watch a specific instance for state changes.
671
+ */
672
+ watchInstance(instanceId: string, options?: WatchOptions): Promise<Subscription>;
673
+ /**
674
+ * Watch all instances matching the filter.
675
+ */
676
+ watchAll(options?: WatchAllOptions): Promise<Subscription>;
677
+ /**
678
+ * Cancel a watch subscription.
679
+ */
680
+ unwatch(subscriptionId: string): Promise<void>;
681
+ on(event: 'connect', listener: () => void): this;
682
+ on(event: 'disconnect', listener: (error?: Error) => void): this;
683
+ on(event: 'error', listener: (error: Error) => void): this;
684
+ on(event: 'reconnect', listener: (attempt: number) => void): this;
685
+ once(event: 'connect', listener: () => void): this;
686
+ once(event: 'disconnect', listener: (error?: Error) => void): this;
687
+ once(event: 'error', listener: (error: Error) => void): this;
688
+ once(event: 'reconnect', listener: (attempt: number) => void): this;
689
+ off(event: 'connect', listener: () => void): this;
690
+ off(event: 'disconnect', listener: (error?: Error) => void): this;
691
+ off(event: 'error', listener: (error: Error) => void): this;
692
+ off(event: 'reconnect', listener: (attempt: number) => void): this;
693
+ }
694
+
695
+ /**
696
+ * Connection-related errors.
697
+ */
698
+ declare class ConnectionError extends RstmdbError {
699
+ constructor(message: string, options?: {
700
+ cause?: Error;
701
+ details?: Record<string, unknown>;
702
+ });
703
+ }
704
+ /**
705
+ * Timeout errors.
706
+ */
707
+ declare class TimeoutError extends RstmdbError {
708
+ constructor(message: string, options?: {
709
+ cause?: Error;
710
+ details?: Record<string, unknown>;
711
+ });
712
+ }
713
+ /**
714
+ * Protocol-level errors.
715
+ */
716
+ declare class ProtocolError extends RstmdbError {
717
+ constructor(message: string, code?: ErrorCode, options?: {
718
+ cause?: Error;
719
+ details?: Record<string, unknown>;
720
+ });
721
+ }
722
+ /**
723
+ * Server-returned errors.
724
+ */
725
+ declare class ServerError extends RstmdbError {
726
+ constructor(message: string, code: ErrorCode, options?: {
727
+ retryable?: boolean;
728
+ details?: Record<string, unknown>;
729
+ cause?: Error;
730
+ });
731
+ /**
732
+ * Create a ServerError from a server response.
733
+ */
734
+ static fromResponse(response: {
735
+ code: string;
736
+ message: string;
737
+ details?: Record<string, unknown>;
738
+ }): ServerError;
739
+ }
740
+ /**
741
+ * Resource not found errors.
742
+ */
743
+ declare class NotFoundError extends ServerError {
744
+ constructor(message: string, code?: ErrorCode, options?: {
745
+ details?: Record<string, unknown>;
746
+ cause?: Error;
747
+ });
748
+ }
749
+ /**
750
+ * Conflict errors (resource already exists, version mismatch, etc.).
751
+ */
752
+ declare class ConflictError extends ServerError {
753
+ constructor(message: string, code?: ErrorCode, options?: {
754
+ details?: Record<string, unknown>;
755
+ cause?: Error;
756
+ });
757
+ }
758
+ /**
759
+ * Authentication errors.
760
+ */
761
+ declare class AuthenticationError extends ServerError {
762
+ constructor(message: string, code?: ErrorCode, options?: {
763
+ details?: Record<string, unknown>;
764
+ cause?: Error;
765
+ });
766
+ }
767
+ /**
768
+ * Invalid state transition errors.
769
+ */
770
+ declare class InvalidTransitionError extends ServerError {
771
+ constructor(message: string, options?: {
772
+ details?: Record<string, unknown>;
773
+ cause?: Error;
774
+ });
775
+ }
776
+ /**
777
+ * Guard condition failed errors.
778
+ */
779
+ declare class GuardFailedError extends ServerError {
780
+ constructor(message: string, options?: {
781
+ details?: Record<string, unknown>;
782
+ cause?: Error;
783
+ });
784
+ }
785
+
786
+ /**
787
+ * RCP frame magic bytes: "RCPX"
788
+ */
789
+ declare const FRAME_MAGIC = 1380143192;
790
+ /**
791
+ * Protocol version.
792
+ */
793
+ declare const PROTOCOL_VERSION = 1;
794
+ /**
795
+ * Frame header size in bytes (4 magic + 2 version + 2 flags + 2 header_len + 4 payload_len + 4 crc).
796
+ */
797
+ declare const HEADER_SIZE = 18;
798
+ /**
799
+ * Frame flags.
800
+ */
801
+ declare enum FrameFlags {
802
+ NONE = 0,
803
+ CRC_PRESENT = 1,
804
+ COMPRESSED = 2,
805
+ STREAM = 4,
806
+ END_STREAM = 8
807
+ }
808
+ /**
809
+ * A decoded RCP frame.
810
+ */
811
+ interface Frame {
812
+ flags: number;
813
+ payload: Buffer;
814
+ }
815
+ /**
816
+ * Encodes a payload into an RCP frame.
817
+ */
818
+ declare class FrameEncoder {
819
+ private readonly useCrc;
820
+ constructor(options?: {
821
+ useCrc?: boolean;
822
+ });
823
+ /**
824
+ * Encode an object into an RCP frame.
825
+ */
826
+ encode(payload: object): Buffer;
827
+ /**
828
+ * Encode a stream frame.
829
+ */
830
+ encodeStream(payload: object, endStream?: boolean): Buffer;
831
+ /**
832
+ * Encode raw payload with specified flags.
833
+ */
834
+ private encodeRaw;
835
+ }
836
+ /**
837
+ * Decodes RCP frames from a byte stream.
838
+ */
839
+ declare class FrameDecoder {
840
+ private buffer;
841
+ private readonly verifyCrc;
842
+ constructor(options?: {
843
+ verifyCrc?: boolean;
844
+ });
845
+ /**
846
+ * Append data to the internal buffer.
847
+ */
848
+ append(data: Buffer): void;
849
+ /**
850
+ * Try to decode a frame from the buffer.
851
+ * Returns null if not enough data is available.
852
+ */
853
+ decode(): Frame | null;
854
+ /**
855
+ * Reset the decoder state.
856
+ */
857
+ reset(): void;
858
+ /**
859
+ * Get the current buffer length.
860
+ */
861
+ get bufferedLength(): number;
862
+ }
863
+
864
+ /**
865
+ * RCP operation types.
866
+ */
867
+ declare enum Operation {
868
+ HELLO = "HELLO",
869
+ AUTH = "AUTH",
870
+ PING = "PING",
871
+ INFO = "INFO",
872
+ PUT_MACHINE = "PUT_MACHINE",
873
+ GET_MACHINE = "GET_MACHINE",
874
+ LIST_MACHINES = "LIST_MACHINES",
875
+ CREATE_INSTANCE = "CREATE_INSTANCE",
876
+ GET_INSTANCE = "GET_INSTANCE",
877
+ DELETE_INSTANCE = "DELETE_INSTANCE",
878
+ APPLY_EVENT = "APPLY_EVENT",
879
+ BATCH = "BATCH",
880
+ WAL_READ = "WAL_READ",
881
+ SNAPSHOT_INSTANCE = "SNAPSHOT_INSTANCE",
882
+ COMPACT = "COMPACT",
883
+ WATCH_INSTANCE = "WATCH_INSTANCE",
884
+ WATCH_ALL = "WATCH_ALL",
885
+ UNWATCH = "UNWATCH"
886
+ }
887
+
888
+ export { type ApplyEventOptions, type ApplyEventResult, AuthenticationError, type BatchOperation, type BatchOptions, type BatchResult, type BatchResultItem, Client, type ClientConfig, type ClientEvents, ClientOptions, type CompactOptions, type CompactResult, ConflictError, ConnectionError, type CreateInstanceOptions, type CreateInstanceResult, DEFAULT_CONFIG, type DeleteInstanceOptions, ErrorCode, FRAME_MAGIC, type Frame, FrameDecoder, FrameEncoder, FrameFlags, type GetInstanceResult, type GetMachineResult, GuardFailedError, HEADER_SIZE, InvalidTransitionError, type ListMachinesOptions, type ListMachinesResult, type MachineDefinition, type MachineListItem, NotFoundError, Operation, PROTOCOL_VERSION, ProtocolError, type PutMachineResult, type ResolvedConfig, RstmdbError, ServerError, type ServerInfo, type SnapshotResult, type StreamEvent, type Subscription, TimeoutError, type TlsConfig, type Transition, type WalEntry, type WalReadOptions, type WalReadResult, type WatchAllOptions, type WatchOptions };