@estiva-app/protocol 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# @estiva-app/protocol
+
+Every entry answers the wire question explicitly, including when the answer is
+nothing (ADR 0002 §4b). A change to the bytes an app publishes is a MAJOR — in
+`0.x`, a MINOR — even when no TypeScript signature moved.
+
+## 0.1.0 — 2026-08-27
+
+First release. SHA-3.
+
+**Wire behaviour: unchanged.** This is an extraction, not a change. The bytes are
+pinned to what `peek-app/convex/nostr/` and `estiva-ship/lib/nostr/` were
+producing before the package existed — `test/wire-vectors.json`, recorded from
+those two trees at `98d284f` and `82e048b` — and all 12 event shapes both apps
+implemented had byte-identical ids in both. Nothing in this release makes an app
+publish a different event than it published yesterday.
+
+Two things arrive here as the union of what the copies had, and neither changes
+an existing app's output:
+
+- **`buildMessage` takes `about`.** Peek's builder emitted `a` tags for
+  cross-app routing; Ship's had no such parameter and could not emit one at all.
+  Peek's shape ships. Omitting `about` produces byte-identical output to Ship's
+  old builder — the `message-*` vectors pin both arms.
+- **`KIND` is the union of both apps' constants.** A kind number is a fact about
+  the relay, not about an app, and a subset is how an app ends up unable to
+  *read* a kind its neighbour writes. Ship gains `NIP29_EDIT_METADATA`,
+  `NIP29_DELETE_GROUP`, `ASSERTION`, `COMMENT` and `RELAY_AUTH` in its type
+  surface; Peek gains `HIGHLIGHT`, `FILE` and `COMPONENT`. Nothing publishes
+  anything new as a result.
+
+One deliberate API reconciliation, called out because it is the one place a call
+site had to change:
+
+- **NIP-98 exports an unsigned builder plus a signer**, which was Peek's shape.
+  Ship had a combined `buildAuthEvent(args & { secretKeyHex })`. The unsigned
+  form is the one that works for an app holding no keys, and the combined form is
+  `signEvent(buildUnsignedAuthEvent(args), secret)` — one line. The *tags* the
+  two produced were already identical; the `nip98-auth-*` vectors pin that.
+
+Also here, moved rather than written: the **relay socket client** (`createLiveRelay`,
+PEE-5) and the **refcounted per-channel subscription manager**
+(`createChannelSubscriptions`, PEE-6). Both were built inside `peek-app` because
+Gate 2 had not happened when they were due, and both were Peek-only until now.
+The only behavioural difference is that the REQ subscription id prefix is a
+`subscriptionPrefix` option instead of the hardcoded `peek-`; it appears in the
+relay's logs and nowhere else.
+
+`Relay`'s second argument now accepts either the bare headers callback it took in
+Ship or an options object (`{ headers, fetch }`), so the existing call sites bind
+unchanged and a test can inject a transport.
+
+### What this release does not include
+
+The fold, and anything that interprets events. `foldFolder` stays in Ship,
+`foldResolution` and the projection stay in Peek, and each app keeps its own
+conformance fixture. See the README on the line this package does not cross.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Estiva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# @estiva-app/protocol
+
+The Estiva wire format, once. Buzz-shaped Nostr event builders, the NIP-01 id
+preimage, NIP-19 `naddr`, NIP-98 HTTP auth, Schnorr signing, and the two relay
+clients.
+
+```bash
+npm install @estiva-app/protocol
+```
+
+No registry auth, no `.npmrc`, no token. That is [ADR 0002 §3](../../../estiva-docs/decisions/0002-foundation-packages.md).
+
+## The line this package does not cross
+
+**In: the bytes.** Everything whose correctness the *relay* judges — event
+construction, tag order, the id hash, the signature input, `naddr`, the NIP-98
+header, and the `accepted` semantics of the HTTP bridge.
+
+**Not in: the fold, or anything that interprets events.** How an app turns a
+stream of events into current truth is where apps are *supposed* to differ
+(ADR 0001 §8). `foldFolder` stays in Ship, `foldResolution` and the projection
+stay in Peek, and each app's conformance fixture stays with it.
+
+When adding something here, the test is not "both apps need it". It is **"would
+the relay notice if the two apps disagreed?"**
+
+## Why one implementation, when the suite's whole claim is independence
+
+SPEC §10 used to argue the duplication *was* the architecture: three apps each
+implementing NIP-01 serialization is what makes "apps sharing no code work on the
+same data" a real statement rather than a claim about siblings.
+
+That was right about the claim and wrong about the mechanism, and the third copy
+settled it. A second hand-written event-id hash is not a demonstration of
+independence, it is a divergence the relay notices and we do not — and it had
+already happened. Peek's `buildMessage` grew an `about` parameter emitting `a`
+tags; Ship's never did. The same logical message produced different bytes
+depending on which app sent it, **nothing failed, and each copy was
+self-consistent.** Between the other two copies, a `diff -r` somebody had to
+remember to run was the entire safety mechanism.
+
+What makes the interop claim true is that the apps share no interpretation and no
+database — still exactly the case. They now agree on the wire format on purpose
+rather than by coincidence. SPEC §10 was amended by SHA-3 to say so.
+
+## A MAJOR here is a protocol event, not a TypeScript event
+
+A change to the bytes an app publishes — id computation, serialization order, tag
+semantics, signature input — is a MAJOR **even when the TypeScript signature is
+identical** (ADR 0002 §4b). Every release note answers the wire question
+explicitly, including when the answer is:
+
+> **Wire behaviour:** unchanged.
+
+A missing line is what lets a bytes-changing release pass as a refactor.
+
+## What holds that claim up
+
+Four checks in CI and a fifth by hand, and the important thing about them is
+that none is a green tick next to a value somebody chose.
+
+| check | what it is |
+| --- | --- |
+| `test/wire.test.mjs` | 21 vectors **recorded from `peek-app/convex/nostr/` and `estiva-ship/lib/nostr/` before this package existed** — the bytes the two apps were already publishing. All 12 shapes both apps implemented had identical ids in both. |
+| the same file, `production kind:*` | 7 events read back off `https://estiva.estiva.app`. Their `id` and `sig` are the **relay's**, so reproducing the id checks against the authority rather than against ourselves. Sampled from the 96 *recorded* events in Ship's fold fixture, not the 7 adversarial ones beside them — those are hand-built and were never published, and one of them sat in this set until the live check queried it back and could not find it. |
+| `test/oracle.test.mjs` | `nostr-tools` as an independent implementation, with a negative control that fails when the bytes are wrong. Plus the canonical NIP-19 `npub` vector from the specification, which is the only thing that catches bech32m-instead-of-bech32. |
+| `test/runtime.test.mjs` | the barrel imports and works with `WebSocket`, `fetch`, `btoa`, `document`, `process`, `Buffer` and friends deleted — with its own negative control. |
+
+**Do not regenerate `wire-vectors.json` to make a failing test pass.** That erases
+the finding. Regenerating is correct only when a builder is deliberately given a
+new shape, and then the release note says so under *Wire behaviour*.
+
+A green suite is still not the last word. The relay is the only authority on
+whether the wire format is right, and a passing test run is compatible with a
+rejected event. So there is a fifth check, and it is hand-run because it needs a
+real workspace credential — and a credential in CI is the standing secret ADR
+0002 §4c spent a failed release deciding not to have:
+
+```bash
+npm run build -w packages/protocol && set -a && . ~/.estiva-agent.env && set +a && npm run verify:live -w packages/protocol
+```
+
+It publishes a **real signed `kind:9007`** naming a channel that already exists,
+so the relay answers `200 {"accepted":false,"duplicate: channel already
+exists"}` — proof the event was parsed, its id recomputed and its signature
+verified — while creating nothing. Then two negative controls, without which "it
+works" is indistinguishable from "the rule was removed":
+
+- the same signed event with **two tags swapped** and `id`/`sig` left alone. The
+  relay's own words, 2026-08-27: `400 invalid: invalid event id: computed
+  70f206d4…, got b9d1e606…`. It recomputes the id independently, so agreement on
+  the good event is agreement about the bytes rather than indifference to them.
+- a `kind:0`, which `/sign` refuses for every app unconditionally —
+  `422 policy_violation`. The gates are live, not open.
+
+Run it before tagging any release whose *Wire behaviour* line is not
+"unchanged", and again afterwards against the **published tarball** rather than
+the workspace, because built is not published.
+
+## `nostr-tools` was evaluated, and is a devDependency rather than a dependency
+
+SHA-3 asked for an hour on this before packaging a hand-rolled hash. Measured,
+2026-08-27, against `nostr-tools@2.25.0`:
+
+| question | answer |
+| --- | --- |
+| does `getEventHash` agree with `computeEventId`? | **Yes, on all 103 events** recorded from production, and on every vector here. `verifyEvent` verified all 103 relay signatures. |
+| does `nip19` round-trip our pointers? | **Yes, exactly** — including a `d` tag containing colons. |
+| is its `naddr` string the same as ours? | **No.** It emits the TLVs in a different order, so the same pointer encodes to a different string. Every decoder involved reads TLVs by type and is order-tolerant, so they interoperate — but naddrs must never be compared as strings. |
+| does its NIP-98 fit? | **No.** `getToken` emits `u`, `method`, `payload` and **no nonce**. Buzz records each auth event id in a Redis replay set and `created_at` has one-second resolution, so two identical requests in one second would collide and the second is refused as `NIP-98: replay detected`. Ours adds a nonce for exactly that reason. |
+| its NIP-42? | `makeAuthEvent` emits relay-then-challenge, which happens to match ours. Buzz looks both tags up by name, so it is not load-bearing either way. |
+| cost of depending on it | it needs `@noble/hashes@2` and `@noble/curves@2`; Peek is on `^1.8.0`/`^1.9.2` and Ship pins `1.8.0`/`1.9.2`. Adopting it puts **two majors of `@noble/*` in every consumer's tree**, and noble v2 renamed its subpaths (`/sha256` → `/sha2`), so it is not a drop-in. |
+| what it does not cover at all | the Buzz kind constants, `canonicalChannelName`, the tag layouts Buzz validates (`h`, the NIP-10 marked-reply form, the `a` about tag), the 30850/30851/1851 shapes, and the `accepted`-field semantics of the bridge. Those stay ours regardless. |
+
+**Decision: keep our own thin implementation and use `nostr-tools` as an
+independent oracle in the test suite.** That is strictly better than either option
+the ticket floated — a third-party cross-check with no dependency, no second
+noble, and no bytes for consumers. It is also what replaces `diff -r`: a check
+that fails on its own rather than one somebody has to remember to run.
+
+## Runtime requirements, and why they are not in the types
+
+The package compiles with `types: []` and no `lib: dom` so one published `.d.ts`
+works in Peek's Convex tree, Peek's browser bundle and the agent's `tsx` run
+(ADR 0002 §4a). None of `URL`, `btoa`, `fetch`, `WebSocket`, `TextDecoder` or the
+timer functions is in `lib.es2022`, so each is **declared inside the module that
+needs it** and **read inside a function body**:
+
+- declaring it inside a module means nothing lands in a consumer's global scope;
+- reading it inside a function means importing the package touches no global, so
+  a backend that only wants the event builders does not crash on a `WebSocket`
+  its runtime has never heard of.
+
+The transport-shaped ones are parameters as well as globals: `Relay` takes an
+optional `fetch`, `createLiveRelay` takes an optional `socketFactory`, and the
+defaults read the runtime's own.
+
+One honest exception, found by writing the test: **`@noble/curves` reads
+`TextEncoder` while its module body runs.** So "no globals at all" is not a
+property this package can have while it depends on `@noble/*`. `TextEncoder`,
+`TextDecoder` and `URL` are WHATWG universals present in every runtime the suite
+targets, and that is the line.
+
+## Consumers
+
+Peek, Ship and `estiva-agent` — see [CONSUMERS.md](../../CONSUMERS.md). A
+breaking change is not published until every one of them has an open upgrade PR,
+authored by whoever makes the break (ADR 0002 §5).
+
+## Releasing
+
+```bash
+git tag protocol@0.1.1 && git push origin protocol@0.1.1
+```
+
+`release.yml` checks the tag against `package.json`, builds, and publishes
+through trusted publishing (OIDC). No npm credential exists in GitHub. See the
+[repo README](../../README.md) for the once-per-package manual first publish.

package/dist/bridge.d.ts

@@ -0,0 +1,91 @@
+import type { SignedEvent } from './events.js';
+import type { Signer } from './sign.js';
+export interface PublishResult {
+    ok: boolean;
+    eventId?: string;
+    reason?: string;
+    /** The relay already had this state — not a failure. */
+    duplicate?: boolean;
+    /** The HTTP status, for a caller that wants to distinguish 403 from 500. */
+    httpStatus?: number;
+}
+/**
+ * The relay's answer to `POST /events`, interpreted.
+ *
+ * `duplicate` is reported as `ok`: "already exists" is the desired end state, so
+ * a caller creating a channel that is already there has succeeded. Every other
+ * `accepted: false` is a failure the caller must surface — SPEC §9's C9, which
+ * is not decoration: once no app can sign locally, an identity-service outage
+ * looks exactly like nothing happening.
+ */
+export declare function parsePublishResponse(status: number, text: string): PublishResult;
+export interface QueryResult {
+    ok: boolean;
+    events: SignedEvent[];
+    reason?: string;
+    httpStatus?: number;
+}
+/** The relay's answer to `POST /query`, interpreted. */
+export declare function parseQueryResponse(status: number, text: string): QueryResult;
+/**
+ * Just enough of `fetch` to post a body and read the answer.
+ *
+ * A parameter rather than an ambient global, per ADR 0002 §4a — `fetch` is in
+ * neither `lib.es2022` nor a package that may assume `lib.dom`. The default
+ * below reads the runtime's own, so no consumer has to pass one.
+ */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    status: number;
+    text(): Promise<string>;
+}>;
+/** Extra headers to send with every relay request, resolved per request. */
+export type RelayHeaders = () => Record<string, string> | Promise<Record<string, string>>;
+export interface RelayOptions {
+    /**
+     * ## Why `headers` is a callback
+     *
+     * Buzz reads more than NIP-98 off a request. A NIP-OA owner attestation travels
+     * in `x-auth-tag`, and on a closed relay it is what admits an agent whose
+     * *owner* is a member — so it is required on **every** call, `/query` included,
+     * not just on writes.
+     *
+     * A callback rather than a fixed object because what it carries can expire: an
+     * agent's attestation is minted with its token and replaced when that token is
+     * renewed. A snapshot taken at construction would work for one TTL and then
+     * fail as a `403 relay_membership_required` that looks nothing like an expiry.
+     *
+     * Empty by default, so an app with no such credential is unaffected.
+     */
+    headers?: RelayHeaders;
+    /** Override the transport. Defaults to the runtime's `fetch`. */
+    fetch?: FetchLike;
+}
+/**
+ * A relay client that signs its own NIP-98 auth.
+ *
+ * Takes a {@link Signer} rather than a key or a token, which is what lets the
+ * same class serve a script holding a secret key and a browser signing through a
+ * remote service.
+ */
+export declare class Relay {
+    private readonly url;
+    private readonly signer;
+    private readonly headers;
+    private readonly transport;
+    constructor(url: string, signer: Signer, options?: RelayOptions | RelayHeaders);
+    private post;
+    publish(event: SignedEvent): Promise<PublishResult>;
+    /**
+     * `filters` is an array — the bridge expects `Vec<Value>`.
+     *
+     * Throws on a transport-level failure rather than returning an empty array,
+     * because "no events" and "the relay refused you" are not the same answer and
+     * a caller that cannot tell them apart renders an empty screen either way.
+     */
+    query(filters: Record<string, unknown>[]): Promise<SignedEvent[]>;
+}
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAEvC,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAehF;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAgB5E;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,KACpE,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAAA;AAKzD,4EAA4E;AAC5E,MAAM,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAEzF,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,iEAAiE;IACjE,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAED;;;;;;GAMG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;gBAErC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,YAAY,GAAG,YAAiB;YAWpE,IAAI;IAwBZ,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAKzD;;;;;;OAMG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;CAMxE"}

package/dist/bridge.js

@@ -0,0 +1,138 @@
+/**
+ * Buzz's HTTP bridge — `POST /events`, `POST /query` — with NIP-98 auth.
+ *
+ * Behaviours here were established against a running relay, not inferred. Three
+ * that bite, and the first is the one that makes a green deploy lie:
+ *
+ *  - **HTTP 200 does not mean accepted.** A duplicate channel create returns
+ *    `200 {"accepted":false,"message":"duplicate: channel already exists"}`.
+ *    The `accepted` field is authoritative and the status code alone would read
+ *    rejections as successes. This is SPEC §5's C3 conformance check.
+ *  - **`/query` takes a bare ARRAY of filters**, not a single filter object.
+ *    Sending one object gets `invalid type: map, expected a sequence`.
+ *  - **A non-member read is answered `403 relay_membership_required`.** There is
+ *    no backend identity that can see anything, which is why reads are
+ *    viewer-driven.
+ *
+ * ## The parsers are exported separately, and that is the point
+ *
+ * {@link parsePublishResponse} and {@link parseQueryResponse} existed twice
+ * before SHA-3 — once in Peek's browser bridge, once in Ship's `Relay` — with
+ * the same `accepted` handling written out both times. They are exported on
+ * their own so an app with its own transport (Peek signs its auth event through
+ * Estiva ID, which is `@estiva-app/identity`'s job, not this package's) still
+ * shares the *interpretation of the answer*. Getting the bytes right and then
+ * reading `200` as success is a way to fail that no test notices.
+ */
+import { authorizationHeader } from './nip98.js';
+/**
+ * The relay's answer to `POST /events`, interpreted.
+ *
+ * `duplicate` is reported as `ok`: "already exists" is the desired end state, so
+ * a caller creating a channel that is already there has succeeded. Every other
+ * `accepted: false` is a failure the caller must surface — SPEC §9's C9, which
+ * is not decoration: once no app can sign locally, an identity-service outage
+ * looks exactly like nothing happening.
+ */
+export function parsePublishResponse(status, text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: `unparseable response: ${text.slice(0, 200)}`, httpStatus: status };
+    }
+    if (status < 200 || status >= 300) {
+        return { ok: false, reason: parsed.error ?? text.slice(0, 200), httpStatus: status };
+    }
+    if (parsed.accepted === false) {
+        const duplicate = (parsed.message ?? '').startsWith('duplicate:');
+        return { ok: duplicate, duplicate, eventId: parsed.event_id, reason: parsed.message, httpStatus: status };
+    }
+    return { ok: true, eventId: parsed.event_id, httpStatus: status };
+}
+/** The relay's answer to `POST /query`, interpreted. */
+export function parseQueryResponse(status, text) {
+    if (status < 200 || status >= 300) {
+        let reason = text.slice(0, 200);
+        try {
+            reason = JSON.parse(text).error ?? reason;
+        }
+        catch {
+            // keep the raw text
+        }
+        return { ok: false, events: [], reason, httpStatus: status };
+    }
+    try {
+        const parsed = JSON.parse(text);
+        return { ok: true, events: Array.isArray(parsed) ? parsed : [], httpStatus: status };
+    }
+    catch {
+        return { ok: false, events: [], reason: `unparseable response: ${text.slice(0, 200)}`, httpStatus: status };
+    }
+}
+/**
+ * A relay client that signs its own NIP-98 auth.
+ *
+ * Takes a {@link Signer} rather than a key or a token, which is what lets the
+ * same class serve a script holding a secret key and a browser signing through a
+ * remote service.
+ */
+export class Relay {
+    url;
+    signer;
+    headers;
+    transport;
+    constructor(url, signer, options = {}) {
+        this.url = url.replace(/\/+$/, '');
+        this.signer = signer;
+        // A bare callback was the old second argument in Ship's client; accepting
+        // both keeps that call site working rather than making a behavioural change
+        // ride along with an extraction.
+        const opts = typeof options === 'function' ? { headers: options } : options;
+        this.headers = opts.headers ?? (() => ({}));
+        this.transport = opts.fetch;
+    }
+    async post(path, payload) {
+        const url = `${this.url}${path}`;
+        const body = JSON.stringify(payload);
+        const auth = await authorizationHeader(this.signer, { url, method: 'POST', body });
+        const send = this.transport ?? fetch;
+        const res = await send(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                ...(await this.headers()),
+                // Rebuilt per request AND unique per request — identical requests in the
+                // same second would otherwise collide on the auth event id and the relay
+                // rejects the second as a replay. See nip98.ts on the nonce.
+                //
+                // Listed after the spread so a caller's headers cannot displace it:
+                // authorization is this client's own contract with the relay, not
+                // something an ambient credential gets to override.
+                authorization: auth,
+            },
+            body,
+        });
+        return { status: res.status, text: await res.text() };
+    }
+    async publish(event) {
+        const { status, text } = await this.post('/events', event);
+        return parsePublishResponse(status, text);
+    }
+    /**
+     * `filters` is an array — the bridge expects `Vec<Value>`.
+     *
+     * Throws on a transport-level failure rather than returning an empty array,
+     * because "no events" and "the relay refused you" are not the same answer and
+     * a caller that cannot tell them apart renders an empty screen either way.
+     */
+    async query(filters) {
+        const { status, text } = await this.post('/query', filters);
+        const result = parseQueryResponse(status, text);
+        if (!result.ok)
+            throw new Error(`query failed: ${result.reason}`);
+        return result.events;
+    }
+}
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"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"}