@proofofbot/client-example

Generated client for the example target. It talks to a wred sidecar over a pipe.

Seals a payload with the demo collector's own primitives

Install

npm install @proofofbot/client-example

The binary for your platform arrives as an optional dependency. Set WRE_BINARY to an absolute path to override it with a local build.

Use

import { ExampleClient } from "@proofofbot/client-example";

const client = await ExampleClient.open({});
const result = await client.hash({ text: "..." });
console.log(result);
await client.close();

One client owns one session, which owns the mounted realm. Open it once and reuse it. Opening one per call pays the warmup cost every time.

Configuration

These fields go in the object you pass to open. The session keeps them for its whole life.

| Field | Type | Default | Description | | --- | --- | --- | --- | | script | string \| null | optional | Script source to mount, overrides the bundled copy | | script_path | string \| null | optional | Path to a script to mount, read by the host process | | key | string | "example" | Seed the collector derives its seal table from | | expect_build | string \| null | optional | Fail with target_drift when the mounted build tag differs | | clock_ms | number \| null | optional | Freeze the realm clock for reproducible payloads | | seed | number \| null | optional | Seed the realm random source | | proxy | string \| null | optional | Proxy used by submit, scheme://user:pass@host:port | | tolerate_throw | boolean | true | - | | timeout_ms | number | 30000 | - |

Operations

client.roles(options)

Which primitives were found in the mounted build

Takes no arguments.

Returns Array<string>.

client.build(options)

The build tag and source digest this session mounted

Takes no arguments.

Returns:

| Field | Type | Description | | --- | --- | --- | | build | string | - | | source_sha | string | - | | roles | Array<string> | - |

client.hash(params, options)

Run the target's own string hash

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | text | string | required | - |

Returns:

| Field | Type | Description | | --- | --- | --- | | value | number | - | | hex | string | - |

client.encode(params, options)

Run the target's own json encoder

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | value | unknown | required | - |

Returns:

| Field | Type | Description | | --- | --- | --- | | text | string | - | | bytes | number | - |

client.seal(params, options)

Encode and seal a value into a wire body

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | value | unknown | required | - | | key | string \| null | optional | Overrides the key seed from the session config |

Returns:

| Field | Type | Description | | --- | --- | --- | | body | string | - | | digest | string | - | | bytes | number | - |

client.payload(params, options)

Build the payload object the collector would send

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | url | string | required | - | | title | string \| null | optional | - | | width | number | 1920 | - | | height | number | 1080 | - | | depth | number | 24 | - | | language | string | "en-US" | - | | timezone | string | "UTC" | - | | webdriver | boolean | false | - | | extra | Record<string, unknown> \| null | optional | - |

Returns unknown.

client.solve(params, options)

Build, encode and seal a payload in one call

Server side deadline: 20 s. Pass a shorter one per call to cap it further.

Streams: progress.

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | url | string | required | - | | title | string \| null | optional | - | | width | number | 1920 | - | | height | number | 1080 | - | | depth | number | 24 | - | | language | string | "en-US" | - | | timezone | string | "UTC" | - | | webdriver | boolean | false | - | | extra | Record<string, unknown> \| null | optional | - |

Returns:

| Field | Type | Description | | --- | --- | --- | | body | string | - | | digest | string | - | | headers | Record<string, string> | - | | build | string | - | | took_ms | number | - |

client.stall(params, options)

Block so deadline and cancel paths can be exercised

Server side deadline: 1 min. Pass a shorter one per call to cap it further.

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | ms | number | 100 | How long to block for |

Returns:

| Field | Type | Description | | --- | --- | --- | | slept_ms | number | - |

client.submit(params, options)

Post a sealed body through the host's http client

Server side deadline: 30 s. Pass a shorter one per call to cap it further.

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | url | string | required | - | | body | string | required | - | | headers | Record<string, string> \| null | optional | - |

Returns:

| Field | Type | Description | | --- | --- | --- | | status | number | - | | ok | boolean | - | | body_sha | string | - |

Events

solve streams progress while it runs. A session is not an emitter, so pass onEvent when you open the client to see every event, or per call to scope it to one:

const client = await ExampleClient.open({}, {
  onEvent: (id, event, data) => console.log(event, data),
});

await client.solve({ url: "https://example.com" }, {
  onEvent: (id, event, data) => console.log(event, data),
});

| Event | Data | Description | | --- | --- | --- | | progress | Progress | Step counter for solve | | log | LogLine | Free text from the client |

Deadlines and cancellation

Every op takes a second options argument: deadlineMs caps the call and fails it with kind === "timeout", signal takes an AbortSignal and fails it with kind === "cancelled". Both stop the work inside the sidecar, they do not only abandon the promise.

const abort = new AbortController();
setTimeout(() => abort.abort(), 5000);
await client.hash({ text: "..." }, { signal: abort.signal });

Errors

Every rejection is a WreError with a stable kind: bad_input, unsupported, target_drift, blocked, timeout, cancelled, resource, protocol, internal. Branch on kind, never on the message. error.retryable says whether the same call is worth repeating.

Sidecar output and diagnostics

The sidecar logs to its own stderr, which is discarded by default. Pass { stderr: "inherit" } to open, or set WRE_STDERR=inherit, to see it.

A failing call writes a diagnostic report and puts its path in error.detail.diagnostics. WRE_DIAG=always records every call, WRE_DIAG=off records none, and await client.diagnose(true) writes one on demand. Send that file with a bug report.

Pinned build

• bundle default
• binary version 0.1.0
• schema hash 26bd761bdc493953

The schema hash is checked at connect time. A mismatch means this package and the installed binary disagree about the callable surface, and the connect call fails.