@freedome/client 0.0.0-stage → 1.0.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,130 @@
1
+ /** Where a dome's media server lives (scheme + host + port; API under /api/v1). */
2
+ declare class FreedomeEndpoint {
3
+ readonly opts: {
4
+ id?: string;
5
+ name?: string;
6
+ tlsFingerprint?: string;
7
+ pairingCode?: string;
8
+ };
9
+ readonly baseUrl: string;
10
+ constructor(baseUrl: string | URL, opts?: {
11
+ id?: string;
12
+ name?: string;
13
+ tlsFingerprint?: string;
14
+ pairingCode?: string;
15
+ });
16
+ /** `host[:port]`, `http(s)://…` or a `freedome://pair?…` link (default port 8080 / 443). */
17
+ static parse(text: string): FreedomeEndpoint;
18
+ get id(): string | undefined;
19
+ get tlsFingerprint(): string | undefined;
20
+ get pairingCode(): string | undefined;
21
+ /** `<base>/api/v1`. */
22
+ get apiBase(): string;
23
+ /** WebSocket base (`ws://` / `wss://`). */
24
+ get wsBase(): string;
25
+ /** Key of the stored tokens / caches (server instance id once known). */
26
+ get storageKey(): string;
27
+ withId(id: string): FreedomeEndpoint;
28
+ toString(): string;
29
+ }
30
+ /** `freedome://pair?host=…&port=…&id=…&code=…&fp=…&tls=1&name=…` (QR code on the dome). */
31
+ declare class PairingLink {
32
+ readonly host: string;
33
+ readonly port: number;
34
+ readonly opts: {
35
+ id?: string;
36
+ code?: string;
37
+ fingerprint?: string;
38
+ tls?: boolean;
39
+ name?: string;
40
+ };
41
+ constructor(host: string, port?: number, opts?: {
42
+ id?: string;
43
+ code?: string;
44
+ fingerprint?: string;
45
+ tls?: boolean;
46
+ name?: string;
47
+ });
48
+ static parse(text: string): PairingLink;
49
+ static tryParse(text: string): PairingLink | null;
50
+ get endpoint(): FreedomeEndpoint;
51
+ toString(): string;
52
+ }
53
+
54
+ /** A connected text-frame socket. */
55
+ interface MessageSocket {
56
+ send(text: string): void;
57
+ /** Registers the frame / close handlers (exactly one pair). */
58
+ listen(onMessage: (text: string) => void, onClose: (code: number | undefined, reason: string | undefined) => void): void;
59
+ close(code?: number, reason?: string): void;
60
+ readonly protocol: string;
61
+ }
62
+ /** Opens a socket to `path` (e.g. `/api/v1/ws`) of [endpoint] with the sub-protocols [protocols]. */
63
+ type MessageSocketConnector = (endpoint: FreedomeEndpoint, path: string, protocols: string[], timeoutMs: number, headers?: Record<string, string>) => Promise<MessageSocket>;
64
+ /** Minimal WHATWG WebSocket shape (browsers, Node ≥ 22, React Native, `ws`). */
65
+ interface WebSocketLike {
66
+ readonly protocol: string;
67
+ readonly readyState: number;
68
+ binaryType?: string;
69
+ send(data: string): void;
70
+ close(code?: number, reason?: string): void;
71
+ onopen: ((ev: unknown) => void) | null;
72
+ onmessage: ((ev: {
73
+ data: unknown;
74
+ }) => void) | null;
75
+ onclose: ((ev: {
76
+ code?: number;
77
+ reason?: string;
78
+ }) => void) | null;
79
+ onerror: ((ev: unknown) => void) | null;
80
+ }
81
+ /** Constructor of a WebSocket implementation. */
82
+ type WebSocketCtor = new (url: string, protocols?: string | string[]) => WebSocketLike;
83
+ /** Connector over a WebSocket constructor (default: `globalThis.WebSocket`). */
84
+ declare function webSocketConnector(impl?: WebSocketCtor): MessageSocketConnector;
85
+
86
+ /** One HTTP request relative to the API base (or the server root when [rootRelative]). */
87
+ interface FreedomeRequest {
88
+ method: string;
89
+ path: string;
90
+ query?: Record<string, string>;
91
+ headers: Record<string, string>;
92
+ body?: Uint8Array | undefined;
93
+ operationId?: string;
94
+ rootRelative?: boolean;
95
+ }
96
+ /** One HTTP response (header names lower-case). */
97
+ declare class FreedomeResponse {
98
+ readonly status: number;
99
+ readonly headers: Record<string, string>;
100
+ readonly body: Uint8Array;
101
+ constructor(status: number, headers?: Record<string, string>, body?: Uint8Array);
102
+ get ok(): boolean;
103
+ get text(): string;
104
+ /** Parsed JSON body (`undefined` when empty). */
105
+ get json(): unknown;
106
+ static json(status: number, value: unknown, headers?: Record<string, string>): FreedomeResponse;
107
+ }
108
+ /** Sends requests to one endpoint. */
109
+ interface FreedomeTransport {
110
+ send(request: FreedomeRequest, timeoutMs: number): Promise<FreedomeResponse>;
111
+ close(): Promise<void>;
112
+ }
113
+ /** Creates transports for an endpoint: REST + (optionally) message sockets for realtime. */
114
+ interface FreedomeTransportFactory {
115
+ rest(endpoint: FreedomeEndpoint): FreedomeTransport;
116
+ readonly sockets: MessageSocketConnector | null;
117
+ }
118
+ /** URL of [r] on [endpoint]. */
119
+ declare function requestUrl(endpoint: FreedomeEndpoint, r: FreedomeRequest): string;
120
+ /** REST over `fetch`. */
121
+ declare class FetchTransport implements FreedomeTransport {
122
+ private readonly endpoint;
123
+ private readonly fetchImpl;
124
+ private readonly controllers;
125
+ constructor(endpoint: FreedomeEndpoint, fetchImpl?: typeof fetch);
126
+ send(r: FreedomeRequest, timeoutMs: number): Promise<FreedomeResponse>;
127
+ close(): Promise<void>;
128
+ }
129
+
130
+ export { FreedomeEndpoint as F, type MessageSocket as M, PairingLink as P, type WebSocketCtor as W, type FreedomeTransportFactory as a, FreedomeResponse as b, FetchTransport as c, type FreedomeRequest as d, type FreedomeTransport as e, type MessageSocketConnector as f, type WebSocketLike as g, requestUrl as r, webSocketConnector as w };
@@ -0,0 +1,130 @@
1
+ /** Where a dome's media server lives (scheme + host + port; API under /api/v1). */
2
+ declare class FreedomeEndpoint {
3
+ readonly opts: {
4
+ id?: string;
5
+ name?: string;
6
+ tlsFingerprint?: string;
7
+ pairingCode?: string;
8
+ };
9
+ readonly baseUrl: string;
10
+ constructor(baseUrl: string | URL, opts?: {
11
+ id?: string;
12
+ name?: string;
13
+ tlsFingerprint?: string;
14
+ pairingCode?: string;
15
+ });
16
+ /** `host[:port]`, `http(s)://…` or a `freedome://pair?…` link (default port 8080 / 443). */
17
+ static parse(text: string): FreedomeEndpoint;
18
+ get id(): string | undefined;
19
+ get tlsFingerprint(): string | undefined;
20
+ get pairingCode(): string | undefined;
21
+ /** `<base>/api/v1`. */
22
+ get apiBase(): string;
23
+ /** WebSocket base (`ws://` / `wss://`). */
24
+ get wsBase(): string;
25
+ /** Key of the stored tokens / caches (server instance id once known). */
26
+ get storageKey(): string;
27
+ withId(id: string): FreedomeEndpoint;
28
+ toString(): string;
29
+ }
30
+ /** `freedome://pair?host=…&port=…&id=…&code=…&fp=…&tls=1&name=…` (QR code on the dome). */
31
+ declare class PairingLink {
32
+ readonly host: string;
33
+ readonly port: number;
34
+ readonly opts: {
35
+ id?: string;
36
+ code?: string;
37
+ fingerprint?: string;
38
+ tls?: boolean;
39
+ name?: string;
40
+ };
41
+ constructor(host: string, port?: number, opts?: {
42
+ id?: string;
43
+ code?: string;
44
+ fingerprint?: string;
45
+ tls?: boolean;
46
+ name?: string;
47
+ });
48
+ static parse(text: string): PairingLink;
49
+ static tryParse(text: string): PairingLink | null;
50
+ get endpoint(): FreedomeEndpoint;
51
+ toString(): string;
52
+ }
53
+
54
+ /** A connected text-frame socket. */
55
+ interface MessageSocket {
56
+ send(text: string): void;
57
+ /** Registers the frame / close handlers (exactly one pair). */
58
+ listen(onMessage: (text: string) => void, onClose: (code: number | undefined, reason: string | undefined) => void): void;
59
+ close(code?: number, reason?: string): void;
60
+ readonly protocol: string;
61
+ }
62
+ /** Opens a socket to `path` (e.g. `/api/v1/ws`) of [endpoint] with the sub-protocols [protocols]. */
63
+ type MessageSocketConnector = (endpoint: FreedomeEndpoint, path: string, protocols: string[], timeoutMs: number, headers?: Record<string, string>) => Promise<MessageSocket>;
64
+ /** Minimal WHATWG WebSocket shape (browsers, Node ≥ 22, React Native, `ws`). */
65
+ interface WebSocketLike {
66
+ readonly protocol: string;
67
+ readonly readyState: number;
68
+ binaryType?: string;
69
+ send(data: string): void;
70
+ close(code?: number, reason?: string): void;
71
+ onopen: ((ev: unknown) => void) | null;
72
+ onmessage: ((ev: {
73
+ data: unknown;
74
+ }) => void) | null;
75
+ onclose: ((ev: {
76
+ code?: number;
77
+ reason?: string;
78
+ }) => void) | null;
79
+ onerror: ((ev: unknown) => void) | null;
80
+ }
81
+ /** Constructor of a WebSocket implementation. */
82
+ type WebSocketCtor = new (url: string, protocols?: string | string[]) => WebSocketLike;
83
+ /** Connector over a WebSocket constructor (default: `globalThis.WebSocket`). */
84
+ declare function webSocketConnector(impl?: WebSocketCtor): MessageSocketConnector;
85
+
86
+ /** One HTTP request relative to the API base (or the server root when [rootRelative]). */
87
+ interface FreedomeRequest {
88
+ method: string;
89
+ path: string;
90
+ query?: Record<string, string>;
91
+ headers: Record<string, string>;
92
+ body?: Uint8Array | undefined;
93
+ operationId?: string;
94
+ rootRelative?: boolean;
95
+ }
96
+ /** One HTTP response (header names lower-case). */
97
+ declare class FreedomeResponse {
98
+ readonly status: number;
99
+ readonly headers: Record<string, string>;
100
+ readonly body: Uint8Array;
101
+ constructor(status: number, headers?: Record<string, string>, body?: Uint8Array);
102
+ get ok(): boolean;
103
+ get text(): string;
104
+ /** Parsed JSON body (`undefined` when empty). */
105
+ get json(): unknown;
106
+ static json(status: number, value: unknown, headers?: Record<string, string>): FreedomeResponse;
107
+ }
108
+ /** Sends requests to one endpoint. */
109
+ interface FreedomeTransport {
110
+ send(request: FreedomeRequest, timeoutMs: number): Promise<FreedomeResponse>;
111
+ close(): Promise<void>;
112
+ }
113
+ /** Creates transports for an endpoint: REST + (optionally) message sockets for realtime. */
114
+ interface FreedomeTransportFactory {
115
+ rest(endpoint: FreedomeEndpoint): FreedomeTransport;
116
+ readonly sockets: MessageSocketConnector | null;
117
+ }
118
+ /** URL of [r] on [endpoint]. */
119
+ declare function requestUrl(endpoint: FreedomeEndpoint, r: FreedomeRequest): string;
120
+ /** REST over `fetch`. */
121
+ declare class FetchTransport implements FreedomeTransport {
122
+ private readonly endpoint;
123
+ private readonly fetchImpl;
124
+ private readonly controllers;
125
+ constructor(endpoint: FreedomeEndpoint, fetchImpl?: typeof fetch);
126
+ send(r: FreedomeRequest, timeoutMs: number): Promise<FreedomeResponse>;
127
+ close(): Promise<void>;
128
+ }
129
+
130
+ export { FreedomeEndpoint as F, type MessageSocket as M, PairingLink as P, type WebSocketCtor as W, type FreedomeTransportFactory as a, FreedomeResponse as b, FetchTransport as c, type FreedomeRequest as d, type FreedomeTransport as e, type MessageSocketConnector as f, type WebSocketLike as g, requestUrl as r, webSocketConnector as w };
package/package.json CHANGED
@@ -1,6 +1,81 @@
1
1
  {
2
2
  "name": "@freedome/client",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.0.0",
4
+ "description": "Isomorphic Freedome client: REST, WebSocket freedome.v1, graphql-ws, socket.io; connection state machine; repositories; offline cache / outbox; codecs (/codecs), Node helpers (/node), in-memory fake (/testing).",
5
+ "license": "NativeMindNONC",
6
+ "homepage": "https://freedome.nativemind.us",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "https://gitlab.com/FreeDome108/freedome_ts.git",
10
+ "directory": "packages/client"
11
+ },
12
+ "type": "module",
13
+ "engines": {
14
+ "node": ">=20"
15
+ },
16
+ "main": "./dist/index.cjs",
17
+ "module": "./dist/index.js",
18
+ "types": "./dist/index.d.ts",
19
+ "exports": {
20
+ ".": {
21
+ "types": "./dist/index.d.ts",
22
+ "import": "./dist/index.js",
23
+ "require": "./dist/index.cjs"
24
+ },
25
+ "./codecs": {
26
+ "types": "./dist/codecs.d.ts",
27
+ "import": "./dist/codecs.js",
28
+ "require": "./dist/codecs.cjs"
29
+ },
30
+ "./node": {
31
+ "types": "./dist/node.d.ts",
32
+ "import": "./dist/node.js",
33
+ "require": "./dist/node.cjs"
34
+ },
35
+ "./testing": {
36
+ "types": "./dist/testing.d.ts",
37
+ "import": "./dist/testing.js",
38
+ "require": "./dist/testing.cjs"
39
+ }
40
+ },
41
+ "files": [
42
+ "dist",
43
+ "LICENSE",
44
+ "README.md",
45
+ "CHANGELOG.md"
46
+ ],
47
+ "dependencies": {
48
+ "fflate": "^0.8.3",
49
+ "socket.io-client": "^4.8.4",
50
+ "@freedome/protocol": "1.0.0"
51
+ },
52
+ "devDependencies": {
53
+ "@types/node": "^22.20.5",
54
+ "@types/ws": "^8.18.2",
55
+ "bonjour-service": "^1.4.4",
56
+ "ws": "^8.21.3",
57
+ "yaml": "^2.9.1"
58
+ },
59
+ "sideEffects": false,
60
+ "peerDependencies": {
61
+ "bonjour-service": "^1.4.4",
62
+ "ws": "^8.21.3"
63
+ },
64
+ "peerDependenciesMeta": {
65
+ "bonjour-service": {
66
+ "optional": true
67
+ },
68
+ "ws": {
69
+ "optional": true
70
+ }
71
+ },
72
+ "publishConfig": {
73
+ "access": "public"
74
+ },
75
+ "scripts": {
76
+ "build": "tsup src/index.ts src/codecs.ts src/node.ts src/testing.ts --format esm,cjs --dts --clean --external ws --external bonjour-service",
77
+ "test": "vitest run",
78
+ "test:integration": "vitest run --config vitest.integration.config.ts",
79
+ "typecheck": "tsc --noEmit -p ."
80
+ }
6
81
  }