@owlmeans/client-socket 0.1.18-rc.1 → 0.1.18-rc.11
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.
- package/README.md +12 -11
- package/agent-meta/manifest.json +2 -2
- package/agent-meta/skills/client-socket/SKILL.md +29 -8
- package/build/helper.d.ts.map +1 -1
- package/build/helper.js +5 -10
- package/build/helper.js.map +1 -1
- package/build/utils/connection.d.ts.map +1 -1
- package/package.json +9 -9
- package/src/helper.ts +5 -10
- package/build/.gitkeep +0 -0
package/README.md
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
# @owlmeans/client-socket
|
|
2
2
|
|
|
3
|
-
React hook and factory for WebSocket connections via OwlMeans
|
|
3
|
+
React hook and factory for WebSocket connections via OwlMeans entrypoint routing.
|
|
4
4
|
|
|
5
5
|
## Overview
|
|
6
6
|
|
|
7
|
-
- `ws(
|
|
8
|
-
- `useWs(
|
|
7
|
+
- `ws(entrypoint, request?)` — creates a `Connection` from the entrypoint's URL and opens a WebSocket
|
|
8
|
+
- `useWs(entrypoint, request?)` — React hook wrapping `ws()` with lifecycle management; it takes an
|
|
9
|
+
alias or an entrypoint
|
|
9
10
|
- The returned `Connection` implements `@owlmeans/socket`'s `Connection` interface
|
|
10
11
|
|
|
11
12
|
## Installation
|
|
@@ -16,7 +17,7 @@ bun add @owlmeans/client-socket
|
|
|
16
17
|
|
|
17
18
|
## Usage
|
|
18
19
|
|
|
19
|
-
Connect to a WebSocket
|
|
20
|
+
Connect to a WebSocket entrypoint and observe events:
|
|
20
21
|
|
|
21
22
|
```typescript
|
|
22
23
|
import { useWs } from '@owlmeans/client-socket'
|
|
@@ -39,19 +40,19 @@ Direct connection (non-hook):
|
|
|
39
40
|
|
|
40
41
|
```typescript
|
|
41
42
|
import { ws } from '@owlmeans/client-socket'
|
|
42
|
-
import type {
|
|
43
|
+
import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
|
|
43
44
|
|
|
44
|
-
const
|
|
45
|
-
const connection = await ws(
|
|
45
|
+
const wsEntrypoint = context.entrypoint<ClientEntrypoint<string>>('story-thinking')
|
|
46
|
+
const connection = await ws(wsEntrypoint, { params: { id: storyId } })
|
|
46
47
|
```
|
|
47
48
|
|
|
48
49
|
## API
|
|
49
50
|
|
|
50
|
-
### `ws(
|
|
51
|
+
### `ws(entrypoint, request?): Promise<Connection>`
|
|
51
52
|
|
|
52
|
-
|
|
53
|
+
Builds the entrypoint's URL, opens a WebSocket, and returns a `Connection` once the socket opens.
|
|
53
54
|
|
|
54
|
-
### `useWs(
|
|
55
|
+
### `useWs(entrypoint, request?): Connection | null`
|
|
55
56
|
|
|
56
57
|
React hook version of `ws()`. Returns `null` while connecting. Manages connection lifecycle (opens on mount, closes on unmount).
|
|
57
58
|
|
|
@@ -59,7 +60,7 @@ React hook version of `ws()`. Returns `null` while connecting. Manages connectio
|
|
|
59
60
|
|
|
60
61
|
- [`@owlmeans/socket`](../socket) — `Connection` interface with `notify`, `observe`, `call` methods
|
|
61
62
|
- [`@owlmeans/server-socket`](../server-socket) — server-side connection handler
|
|
62
|
-
- [`@owlmeans/client-
|
|
63
|
+
- [`@owlmeans/client-entrypoint`](../client-entrypoint) — `ClientEntrypoint` passed to `ws()`
|
|
63
64
|
|
|
64
65
|
<!-- owlmeans:agent-guidance:start -->
|
|
65
66
|
## Agent guidance
|
package/agent-meta/manifest.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 2,
|
|
3
3
|
"package": "@owlmeans/client-socket",
|
|
4
|
-
"version": "0.1.18-rc.
|
|
5
|
-
"generatedAt": "2026-
|
|
4
|
+
"version": "0.1.18-rc.11",
|
|
5
|
+
"generatedAt": "2026-09-01T16:28:56.987Z",
|
|
6
6
|
"canonicalRepo": "https://github.com/owlmeans/common",
|
|
7
7
|
"entries": [
|
|
8
8
|
{
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: client-socket
|
|
3
|
-
description: How to use @owlmeans/client-socket —
|
|
3
|
+
description: How to use @owlmeans/client-socket — opening a WebSocket connection to a socket entrypoint from browsers and native clients, plus the useWs hook. Auto-invoked when importing client socket primitives.
|
|
4
4
|
user-invocable: false
|
|
5
5
|
---
|
|
6
6
|
<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
|
|
@@ -8,23 +8,44 @@ user-invocable: false
|
|
|
8
8
|
# @owlmeans/client-socket
|
|
9
9
|
|
|
10
10
|
**Layer:** Client
|
|
11
|
-
**Install:** `"@owlmeans/client-socket": "^0.1.18-rc.
|
|
11
|
+
**Install:** `"@owlmeans/client-socket": "^0.1.18-rc.11"` in `dependencies`
|
|
12
12
|
|
|
13
13
|
## Key Exports
|
|
14
14
|
|
|
15
15
|
| Export | Description |
|
|
16
16
|
|--------|-------------|
|
|
17
|
-
| `
|
|
18
|
-
|
|
|
17
|
+
| `ws(entrypoint, request?)` | Open a `Connection` to a socket entrypoint |
|
|
18
|
+
| `useWs(entrypoint \| alias, request?)` | React hook — connects, keeps the connection, closes it on unmount |
|
|
19
|
+
| `Config` / `Context` | The client config and context types this package expects |
|
|
20
|
+
|
|
21
|
+
## How the address is built
|
|
22
|
+
|
|
23
|
+
A socket entrypoint is **addressed, not called**: `entrypointUrl` from
|
|
24
|
+
`@owlmeans/client-entrypoint/utils` turns the declaration plus the asking context into the `wss://`
|
|
25
|
+
URL — `:params` filled in, query appended, protocol and TLS taken from the entrypoint's address —
|
|
26
|
+
and the connection is opened on that. Nothing is hand-concatenated, so the same declaration that the
|
|
27
|
+
server binds is the one the client dials.
|
|
28
|
+
|
|
29
|
+
The connection sends a `ping` every 30 seconds and clears the heartbeat on close.
|
|
19
30
|
|
|
20
31
|
## Usage
|
|
21
32
|
|
|
22
33
|
```typescript
|
|
23
|
-
import {
|
|
24
|
-
|
|
25
|
-
|
|
34
|
+
import { useWs } from '@owlmeans/client-socket'
|
|
35
|
+
import { AUTH_QUERY } from '@owlmeans/auth'
|
|
36
|
+
|
|
37
|
+
const connection = useWs(app.api.project.stream, {
|
|
38
|
+
params: { id },
|
|
39
|
+
query: { [AUTH_QUERY]: token },
|
|
40
|
+
})
|
|
41
|
+
|
|
42
|
+
connection?.listen(async message => { /* ... */ })
|
|
26
43
|
```
|
|
27
44
|
|
|
45
|
+
`useWs` reconnects when the alias, the auth query value or the params change, and closes the
|
|
46
|
+
connection when the component unmounts.
|
|
47
|
+
|
|
28
48
|
## Depends On
|
|
29
49
|
|
|
30
|
-
- `@owlmeans/socket`, `@owlmeans/client-context`
|
|
50
|
+
- `@owlmeans/socket`, `@owlmeans/client-entrypoint` (`entrypointUrl`, `provideRequest`), `@owlmeans/client-context`
|
|
51
|
+
- `@owlmeans/client` — `useContext`, `useValue`
|
package/build/helper.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;
|
|
1
|
+
{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AASlD,eAAO,MAAM,EAAE,GAAU,QAAQ,gBAAgB,CAAC,MAAM,CAAC,EAAE,UAAU,eAAe,CAAC;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,KAAG,OAAO,CAAC,UAAU,CAuB5H,CAAA;AAED,eAAO,MAAM,KAAK,GAAI,QAAQ,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,EAAE,UAAU,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,KAAG,UAAU,GAAG,IAyBpH,CAAA"}
|
package/build/helper.js
CHANGED
|
@@ -1,19 +1,14 @@
|
|
|
1
1
|
import { provideRequest } from '@owlmeans/client-entrypoint';
|
|
2
|
-
import { EntrypointOutcome } from '@owlmeans/entrypoint';
|
|
3
|
-
import { SocketInitializationError } from '@owlmeans/socket';
|
|
4
2
|
import { makeConnection } from './utils/connection.js';
|
|
5
3
|
import { assertContext } from '@owlmeans/context';
|
|
6
4
|
import { useContext, useValue } from '@owlmeans/client';
|
|
7
5
|
import { AUTH_QUERY } from '@owlmeans/auth';
|
|
8
|
-
import {
|
|
6
|
+
import { entrypointUrl } from '@owlmeans/client-entrypoint/utils';
|
|
9
7
|
import { useEffect, useMemo } from 'react';
|
|
10
8
|
export const ws = async (module, request) => {
|
|
11
9
|
const ctx = assertContext(module.ctx, 'client-ws');
|
|
12
|
-
request = request ?? provideRequest(module.
|
|
13
|
-
const
|
|
14
|
-
if (state !== EntrypointOutcome.Ok) {
|
|
15
|
-
throw new SocketInitializationError;
|
|
16
|
-
}
|
|
10
|
+
request = request ?? provideRequest(module.alias, module.path());
|
|
11
|
+
const url = await entrypointUrl({ ref: module }, request);
|
|
17
12
|
const socket = new WebSocket(url);
|
|
18
13
|
return new Promise(resolve => {
|
|
19
14
|
socket.onopen = () => {
|
|
@@ -34,11 +29,11 @@ export const useWs = (module, request) => {
|
|
|
34
29
|
const ctx = useContext();
|
|
35
30
|
const mod = useMemo(() => typeof module === 'string' ? ctx.entrypoint(module) : module, [module]);
|
|
36
31
|
const connection = useValue(async () => {
|
|
37
|
-
const _request = provideRequest(mod.
|
|
32
|
+
const _request = provideRequest(mod.alias, mod.path());
|
|
38
33
|
Object.assign(_request, request);
|
|
39
34
|
return await ws(mod, _request);
|
|
40
35
|
}, [
|
|
41
|
-
mod.
|
|
36
|
+
mod.alias,
|
|
42
37
|
request?.query?.[AUTH_QUERY],
|
|
43
38
|
request?.params ? JSON.stringify(request.params) : undefined
|
|
44
39
|
]);
|
package/build/helper.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;
|
|
1
|
+
{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/utils/connection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAA4B,MAAM,kBAAkB,CAAA;AAG5E,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,
|
|
1
|
+
{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/utils/connection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAA4B,MAAM,kBAAkB,CAAA;AAG5E,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACzF,MAAM,SAAS,EAAE,UAAU,CAAC,KAC3B,UAkDF,CAAA"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@owlmeans/client-socket",
|
|
3
|
-
"version": "0.1.18-rc.
|
|
3
|
+
"version": "0.1.18-rc.11",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
|
@@ -30,14 +30,14 @@
|
|
|
30
30
|
"typescript": "^7.0.2"
|
|
31
31
|
},
|
|
32
32
|
"dependencies": {
|
|
33
|
-
"@owlmeans/auth": "^0.1.18-rc.
|
|
34
|
-
"@owlmeans/basic-envelope": "^0.1.18-rc.
|
|
35
|
-
"@owlmeans/client": "^0.1.18-rc.
|
|
36
|
-
"@owlmeans/client-context": "^0.1.18-rc.
|
|
37
|
-
"@owlmeans/client-entrypoint": "^0.1.18-rc.
|
|
38
|
-
"@owlmeans/context": "^0.1.18-rc.
|
|
39
|
-
"@owlmeans/entrypoint": "^0.1.18-rc.
|
|
40
|
-
"@owlmeans/socket": "^0.1.18-rc.
|
|
33
|
+
"@owlmeans/auth": "^0.1.18-rc.8",
|
|
34
|
+
"@owlmeans/basic-envelope": "^0.1.18-rc.10",
|
|
35
|
+
"@owlmeans/client": "^0.1.18-rc.13",
|
|
36
|
+
"@owlmeans/client-context": "^0.1.18-rc.11",
|
|
37
|
+
"@owlmeans/client-entrypoint": "^0.1.18-rc.11",
|
|
38
|
+
"@owlmeans/context": "^0.1.18-rc.7",
|
|
39
|
+
"@owlmeans/entrypoint": "^0.1.18-rc.9",
|
|
40
|
+
"@owlmeans/socket": "^0.1.18-rc.8"
|
|
41
41
|
},
|
|
42
42
|
"publishConfig": {
|
|
43
43
|
"access": "public"
|
package/src/helper.ts
CHANGED
|
@@ -1,25 +1,20 @@
|
|
|
1
1
|
import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
|
|
2
2
|
import type { AbstractRequest } from '@owlmeans/entrypoint'
|
|
3
3
|
import { provideRequest } from '@owlmeans/client-entrypoint'
|
|
4
|
-
import { EntrypointOutcome } from '@owlmeans/entrypoint'
|
|
5
4
|
import type { Connection } from '@owlmeans/socket'
|
|
6
|
-
import { SocketInitializationError } from '@owlmeans/socket'
|
|
7
5
|
import { makeConnection } from './utils/connection.js'
|
|
8
6
|
import { assertContext } from '@owlmeans/context'
|
|
9
7
|
import type { Config, Context } from './types.js'
|
|
10
8
|
import { useContext, useValue } from '@owlmeans/client'
|
|
11
9
|
import { AUTH_QUERY } from '@owlmeans/auth'
|
|
12
|
-
import {
|
|
10
|
+
import { entrypointUrl } from '@owlmeans/client-entrypoint/utils'
|
|
13
11
|
import { useEffect, useMemo } from 'react'
|
|
14
12
|
|
|
15
13
|
export const ws = async (module: ClientEntrypoint<string>, request?: AbstractRequest<{ token?: string }>): Promise<Connection> => {
|
|
16
14
|
const ctx = assertContext<Config, Context>(module.ctx as Context, 'client-ws')
|
|
17
|
-
request = request ?? provideRequest(module.
|
|
18
|
-
const
|
|
15
|
+
request = request ?? provideRequest(module.alias, module.path())
|
|
16
|
+
const url = await entrypointUrl({ ref: module }, request)
|
|
19
17
|
|
|
20
|
-
if (state !== EntrypointOutcome.Ok) {
|
|
21
|
-
throw new SocketInitializationError
|
|
22
|
-
}
|
|
23
18
|
const socket = new WebSocket(url)
|
|
24
19
|
|
|
25
20
|
return new Promise(resolve => {
|
|
@@ -47,11 +42,11 @@ export const useWs = (module: string | ClientEntrypoint<any>, request?: Partial<
|
|
|
47
42
|
[module]
|
|
48
43
|
)
|
|
49
44
|
const connection = useValue<Connection>(async () => {
|
|
50
|
-
const _request = provideRequest(mod.
|
|
45
|
+
const _request = provideRequest(mod.alias, mod.path())
|
|
51
46
|
Object.assign(_request, request)
|
|
52
47
|
return await ws(mod, _request)
|
|
53
48
|
}, [
|
|
54
|
-
mod.
|
|
49
|
+
mod.alias,
|
|
55
50
|
request?.query?.[AUTH_QUERY],
|
|
56
51
|
request?.params ? JSON.stringify(request.params) : undefined
|
|
57
52
|
])
|
package/build/.gitkeep
DELETED
|
File without changes
|