@atproto/tap 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @atproto/tap
+
+## 0.0.2
+
+### Patch Changes
+
+- [#4290](https://github.com/bluesky-social/atproto/pull/4290) [`b4a76ba`](https://github.com/bluesky-social/atproto/commit/b4a76bae7bef1189302488d43ce49a03fd61f957) Thanks [@dholms](https://github.com/dholms)! - Initial version of package
+
+- Updated dependencies [[`b4a76ba`](https://github.com/bluesky-social/atproto/commit/b4a76bae7bef1189302488d43ce49a03fd61f957)]:
+  - @atproto/ws-client@0.0.4

package/LICENSE.txt

@@ -0,0 +1,7 @@
+Dual MIT/Apache-2.0 License
+
+Copyright (c) 2022-2025 Bluesky Social PBC, and Contributors
+
+Except as otherwise noted in individual files, this software is licensed under the MIT license (<http://opensource.org/licenses/MIT>), or the Apache License, Version 2.0 (<http://www.apache.org/licenses/LICENSE-2.0>).
+
+Downstream projects and end users may chose either license individually, or both together, at their discretion. The motivation for this dual-licensing is the additional software patent assurance provided by Apache 2.0.

package/README.md

@@ -0,0 +1,221 @@
+# @atproto/tap
+
+TypeScript client library for [Tap](https://github.com/bluesky-social/indigo/tree/main/cmd/tap/README.md), a sync utility for the AT Protocol network.
+
+Tap handles firehose connections, cryptographic verification, backfill, and filtering. This client library lets you connect to a Tap instance and receive simple JSON events for the repos you care about.
+
+[![NPM](https://img.shields.io/npm/v/@atproto/tap)](https://www.npmjs.com/package/@atproto/tap)
+[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
+
+## Quick Start
+
+```bash
+npm install @atproto/tap
+```
+
+```ts
+import { Tap, SimpleIndexer } from '@atproto/tap'
+
+const tap = new Tap('http://localhost:2480', { adminPassword: 'secret' })
+
+const indexer = new SimpleIndexer()
+
+indexer.identity(async (evt) => {
+  console.log(`${evt.did} updated identity: ${evt.handle} (${evt.status})`)
+})
+
+indexer.record(async (evt) => {
+  const uri = `at://${evt.did}/${evt.collection}/${evt.rkey}`
+  if (evt.action === 'create' || evt.action === 'update') {
+    console.log(`${evt.action}: ${uri}`)
+  } else {
+    console.log(`deleted: ${uri}`)
+  }
+})
+
+indexer.error((err) => console.error(err))
+
+const channel = tap.channel(indexer)
+channel.start()
+
+await tap.addRepos(['did:plc:ewvi7nxzyoun6zhxrhs64oiz'])
+
+// On shutdown
+await channel.destroy()
+```
+
+## Running Tap
+
+See the [Tap README](https://github.com/bluesky-social/indigo/tree/main/cmd/tap/README.md) for details getting Tap up and running. Your app can communicate with it either locally or over the internet.
+
+This library is intended to be used with Tap running in the default mode of "WebScoket with acks". In this mode, Tap provides:
+
+- **At-least-once delivery**: Events may be redelivered if the connection drops before an ack is received
+- **Per-repo ordering**: Events for the same repo are delivered in order
+- **Backfill**: When you add a repo, historical events are delivered before live events
+
+## API
+
+### `Tap`
+
+The main client for interacting with a Tap server.
+
+```ts
+const tap = new Tap(url: string, config?: TapConfig)
+```
+
+**Config options:**
+
+- `adminPassword?: string` - Password for Basic auth (required if Tap server has auth enabled)
+
+**Methods:**
+
+- `channel(handler: TapHandler, opts?: TapWebsocketOptions): TapChannel` - Create a WebSocket channel to receive events
+- `addRepos(dids: string[]): Promise<void>` - Add repos to track (triggers backfill)
+- `removeRepos(dids: string[]): Promise<void>` - Stop tracking repos
+- `resolveDid(did: string): Promise<DidDocument | null>` - Resolve a DID to its DID document
+- `getRepoInfo(did: string): Promise<RepoInfo>` - Get info about a tracked repo
+
+### `TapChannel`
+
+WebSocket connection for receiving events. Created via `tap.channel()`.
+
+```ts
+const channel = tap.channel(handler, opts?)
+```
+
+**Methods:**
+
+- `start(): Promise<void>` - Start receiving events. Returns a promise that resolves when the connection is destroyed or errors.
+- `destroy(): Promise<void>` - Close the connection
+
+The channel automatically handles reconnection and keepalive. Events are automatically acknowledged after your handler completes successfully.
+
+### `SimpleIndexer`
+
+A convenience class for handling events by type. Passed into `tap.channel()` when opening a channel with Tap.
+
+```ts
+const indexer = new SimpleIndexer()
+
+indexer.identity(async (evt: IdentityEvent) => { ... })
+indexer.record(async (evt: RecordEvent) => { ... })
+indexer.error((err: Error) => { ... })
+```
+
+If no error handler is registered, errors will throw as unhandled exceptions.
+
+### `TapHandler`
+
+You can create your own custom handler by creating a class that implements the `TapHandler` interface:
+
+```ts
+interface TapHandler {
+  onEvent: (evt: TapEvent, opts: HandlerOpts) => void | Promise<void>
+  onError: (err: Error) => void
+}
+
+interface HandlerOpts {
+  signal: AbortSignal
+  ack: () => Promise<void>
+}
+```
+
+When implementing a custom handler, be sure to call `ack()` when you're done processing the event.
+
+## Event Types
+
+### `RecordEvent`
+
+```ts
+type RecordEvent = {
+  id: number
+  type: 'record'
+  action: 'create' | 'update' | 'delete'
+  did: string
+  rev: string
+  collection: string
+  rkey: string
+  record?: Record<string, unknown> // present for create/update
+  cid?: string // present for create/update
+  live: boolean // true if from firehose, false if from backfill
+}
+```
+
+### `IdentityEvent`
+
+```ts
+type IdentityEvent = {
+  id: number
+  type: 'identity'
+  did: string
+  handle: string
+  isActive: boolean
+  status: 'active' | 'takendown' | 'suspended' | 'deactivated' | 'deleted'
+}
+```
+
+## Webhook Mode
+
+If your Tap server is configured for webhook delivery, you can use `parseTapEvent` to validate incoming webhook payloads:
+
+```ts
+import express from 'express'
+import { parseTapEvent, assureAdminAuth } from '@atproto/tap'
+
+const ADMIN_PASSWORD = process.env.ADMIN_PASSWORD
+
+const app = express()
+app.use(express.json())
+
+app.post('/webhook', async (req, res) => {
+  try {
+    assureAdminAuth(ADMIN_PASSWORD, req.headers.authorization)
+  } catch {
+    return res.status(401).json({ error: 'Unauthorized' })
+  }
+
+  try {
+    const evt = parseTapEvent(req.body)
+    // handle event...
+    res.sendStatus(200)
+  } catch (err) {
+    console.error('Failed to process event:', err)
+    res.status(500).json({ error: 'Failed to process event' })
+  }
+})
+```
+
+## Utilities
+
+### Auth helpers
+
+```ts
+import {
+  formatAdminAuthHeader,
+  parseAdminAuthHeader,
+  assureAdminAuth,
+} from '@atproto/tap'
+
+// Format a password into a Basic auth header value
+const header = formatAdminAuthHeader('secret')
+// => 'Basic YWRtaW46c2VjcmV0'
+
+// Parse an auth header to extract the password (throws if invalid)
+const password = parseAdminAuthHeader(header)
+
+// Verify auth header matches expected password (timing-safe, throws if invalid)
+assureAdminAuth('secret', req.headers.authorization)
+```
+
+### Event parsing
+
+```ts
+import { parseTapEvent } from '@atproto/tap'
+
+const evt = parseTapEvent(jsonData) // validates and returns typed TapEvent
+```
+
+## License
+
+MIT

package/dist/channel.d.ts

@@ -0,0 +1,32 @@
+import { ClientOptions } from 'ws';
+import { TapEvent } from './types';
+export interface HandlerOpts {
+    signal: AbortSignal;
+    ack: () => Promise<void>;
+}
+export interface TapHandler {
+    onEvent: (evt: TapEvent, opts: HandlerOpts) => void | Promise<void>;
+    onError: (err: Error) => void;
+}
+export type TapWebsocketOptions = ClientOptions & {
+    adminPassword?: string;
+    maxReconnectSeconds?: number;
+    heartbeatIntervalMs?: number;
+    onReconnectError?: (error: unknown, n: number, initialSetup: boolean) => void;
+};
+export declare class TapChannel {
+    private ws;
+    private handler;
+    private readonly abortController;
+    private readonly destroyDefer;
+    private bufferedAcks;
+    constructor(url: string, handler: TapHandler, wsOpts?: TapWebsocketOptions);
+    ackEvent(id: number): Promise<void>;
+    private sendAck;
+    private bufferAndSendAck;
+    private flushBufferedAcks;
+    start(): Promise<void>;
+    private processWsEvent;
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,IAAI,CAAA;AAGlC,OAAO,EAAE,QAAQ,EAAiB,MAAM,SAAS,CAAA;AAGjD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAA;IACnB,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnE,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAA;CAC9B;AAED,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG;IAChD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,KAAK,IAAI,CAAA;CAC9E,CAAA;AAOD,qBAAa,UAAU;IACrB,OAAO,CAAC,EAAE,CAAoB;IAC9B,OAAO,CAAC,OAAO,CAAY;IAE3B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyC;IACzE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiC;IAE9D,OAAO,CAAC,YAAY,CAAoB;gBAGtC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,UAAU,EACnB,MAAM,GAAE,mBAAwB;IAoB5B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAY3B,OAAO;YAKP,gBAAgB;YAShB,iBAAiB;IAqBzB,KAAK;YAcG,cAAc;IA0BtB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAI/B"}

package/dist/channel.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TapChannel = void 0;
+const common_1 = require("@atproto/common");
+const ws_client_1 = require("@atproto/ws-client");
+const types_1 = require("./types");
+const util_1 = require("./util");
+class TapChannel {
+    constructor(url, handler, wsOpts = {}) {
+        Object.defineProperty(this, "ws", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "handler", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "abortController", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new AbortController()
+        });
+        Object.defineProperty(this, "destroyDefer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (0, common_1.createDeferrable)()
+        });
+        Object.defineProperty(this, "bufferedAcks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        this.handler = handler;
+        const { adminPassword, ...rest } = wsOpts;
+        let headers = rest.headers;
+        if (adminPassword) {
+            headers ?? (headers = {});
+            headers['Authorization'] = (0, util_1.formatAdminAuthHeader)(adminPassword);
+        }
+        this.ws = new ws_client_1.WebSocketKeepAlive({
+            getUrl: async () => url,
+            onReconnect: () => {
+                this.flushBufferedAcks();
+            },
+            signal: this.abortController.signal,
+            ...rest,
+            headers,
+        });
+    }
+    async ackEvent(id) {
+        if (this.ws.isConnected()) {
+            try {
+                await this.sendAck(id);
+            }
+            catch {
+                await this.bufferAndSendAck(id);
+            }
+        }
+        else {
+            await this.bufferAndSendAck(id);
+        }
+    }
+    async sendAck(id) {
+        await this.ws.send(JSON.stringify({ type: 'ack', id }));
+    }
+    // resolves after the ack has been actually sent
+    async bufferAndSendAck(id) {
+        const defer = (0, common_1.createDeferrable)();
+        this.bufferedAcks.push({
+            id,
+            defer,
+        });
+        await defer.complete;
+    }
+    async flushBufferedAcks() {
+        while (this.bufferedAcks.length > 0) {
+            try {
+                const ack = this.bufferedAcks.at(0);
+                if (!ack) {
+                    return;
+                }
+                await this.sendAck(ack.id);
+                ack.defer.resolve();
+                this.bufferedAcks = this.bufferedAcks.slice(1);
+            }
+            catch (err) {
+                this.handler.onError(new Error(`failed to send ack for event ${this.bufferedAcks[0]}`, {
+                    cause: err,
+                }));
+                return;
+            }
+        }
+    }
+    async start() {
+        try {
+            for await (const chunk of this.ws) {
+                await this.processWsEvent(chunk);
+            }
+        }
+        catch (err) {
+            if ((0, common_1.isErrnoException)(err) && err.name === 'AbortError') {
+                this.destroyDefer.resolve();
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    async processWsEvent(chunk) {
+        let evt;
+        try {
+            const data = chunk.toString();
+            evt = (0, types_1.parseTapEvent)(JSON.parse(data));
+        }
+        catch (err) {
+            this.handler.onError(new Error('Failed to parse message', { cause: err }));
+            return;
+        }
+        try {
+            await this.handler.onEvent(evt, {
+                signal: this.abortController.signal,
+                ack: async () => {
+                    await this.ackEvent(evt.id);
+                },
+            });
+        }
+        catch (err) {
+            // Don't ack on error - let Tap retry
+            this.handler.onError(new Error(`Failed to process event ${evt.id}`, { cause: err }));
+            return;
+        }
+    }
+    async destroy() {
+        this.abortController.abort();
+        await this.destroyDefer.complete;
+    }
+}
+exports.TapChannel = TapChannel;
+//# sourceMappingURL=channel.js.map

package/dist/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"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","sourcesContent":["import { ClientOptions } from 'ws'\nimport { Deferrable, createDeferrable, isErrnoException } from '@atproto/common'\nimport { WebSocketKeepAlive } from '@atproto/ws-client'\nimport { TapEvent, parseTapEvent } from './types'\nimport { formatAdminAuthHeader } from './util'\n\nexport interface HandlerOpts {\n  signal: AbortSignal\n  ack: () => Promise<void>\n}\n\nexport interface TapHandler {\n  onEvent: (evt: TapEvent, opts: HandlerOpts) => void | Promise<void>\n  onError: (err: Error) => void\n}\n\nexport type TapWebsocketOptions = ClientOptions & {\n  adminPassword?: string\n  maxReconnectSeconds?: number\n  heartbeatIntervalMs?: number\n  onReconnectError?: (error: unknown, n: number, initialSetup: boolean) => void\n}\n\ntype BufferedAck = {\n  id: number\n  defer: Deferrable\n}\n\nexport class TapChannel {\n  private ws: WebSocketKeepAlive\n  private handler: TapHandler\n\n  private readonly abortController: AbortController = new AbortController()\n  private readonly destroyDefer: Deferrable = createDeferrable()\n\n  private bufferedAcks: BufferedAck[] = []\n\n  constructor(\n    url: string,\n    handler: TapHandler,\n    wsOpts: TapWebsocketOptions = {},\n  ) {\n    this.handler = handler\n    const { adminPassword, ...rest } = wsOpts\n    let headers = rest.headers\n    if (adminPassword) {\n      headers ??= {}\n      headers['Authorization'] = formatAdminAuthHeader(adminPassword)\n    }\n    this.ws = new WebSocketKeepAlive({\n      getUrl: async () => url,\n      onReconnect: () => {\n        this.flushBufferedAcks()\n      },\n      signal: this.abortController.signal,\n      ...rest,\n      headers,\n    })\n  }\n\n  async ackEvent(id: number): Promise<void> {\n    if (this.ws.isConnected()) {\n      try {\n        await this.sendAck(id)\n      } catch {\n        await this.bufferAndSendAck(id)\n      }\n    } else {\n      await this.bufferAndSendAck(id)\n    }\n  }\n\n  private async sendAck(id: number): Promise<void> {\n    await this.ws.send(JSON.stringify({ type: 'ack', id }))\n  }\n\n  // resolves after the ack has been actually sent\n  private async bufferAndSendAck(id: number): Promise<void> {\n    const defer = createDeferrable()\n    this.bufferedAcks.push({\n      id,\n      defer,\n    })\n    await defer.complete\n  }\n\n  private async flushBufferedAcks(): Promise<void> {\n    while (this.bufferedAcks.length > 0) {\n      try {\n        const ack = this.bufferedAcks.at(0)\n        if (!ack) {\n          return\n        }\n        await this.sendAck(ack.id)\n        ack.defer.resolve()\n        this.bufferedAcks = this.bufferedAcks.slice(1)\n      } catch (err) {\n        this.handler.onError(\n          new Error(`failed to send ack for event ${this.bufferedAcks[0]}`, {\n            cause: err,\n          }),\n        )\n        return\n      }\n    }\n  }\n\n  async start() {\n    try {\n      for await (const chunk of this.ws) {\n        await this.processWsEvent(chunk)\n      }\n    } catch (err) {\n      if (isErrnoException(err) && err.name === 'AbortError') {\n        this.destroyDefer.resolve()\n      } else {\n        throw err\n      }\n    }\n  }\n\n  private async processWsEvent(chunk: Uint8Array) {\n    let evt: TapEvent\n    try {\n      const data = chunk.toString()\n      evt = parseTapEvent(JSON.parse(data))\n    } catch (err) {\n      this.handler.onError(new Error('Failed to parse message', { cause: err }))\n      return\n    }\n\n    try {\n      await this.handler.onEvent(evt, {\n        signal: this.abortController.signal,\n        ack: async () => {\n          await this.ackEvent(evt.id)\n        },\n      })\n    } catch (err) {\n      // Don't ack on error - let Tap retry\n      this.handler.onError(\n        new Error(`Failed to process event ${evt.id}`, { cause: err }),\n      )\n      return\n    }\n  }\n\n  async destroy(): Promise<void> {\n    this.abortController.abort()\n    await this.destroyDefer.complete\n  }\n}\n"]}

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import { DidDocument } from '@atproto/common';
+import { TapChannel, TapHandler, TapWebsocketOptions } from './channel';
+import { RepoInfo } from './types';
+export interface TapConfig {
+    adminPassword?: string;
+}
+export declare class Tap {
+    url: string;
+    private adminPassword?;
+    private authHeader?;
+    constructor(url: string, config?: TapConfig);
+    private getHeaders;
+    channel(handler: TapHandler, opts?: TapWebsocketOptions): TapChannel;
+    addRepos(dids: string[]): Promise<void>;
+    removeRepos(dids: string[]): Promise<void>;
+    resolveDid(did: string): Promise<DidDocument | null>;
+    getRepoInfo(did: string): Promise<RepoInfo>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAe,MAAM,iBAAiB,CAAA;AAC1D,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AACvE,OAAO,EAAE,QAAQ,EAAkB,MAAM,SAAS,CAAA;AAGlD,MAAM,WAAW,SAAS;IACxB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,qBAAa,GAAG;IACd,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,CAAC,aAAa,CAAC,CAAQ;IAC9B,OAAO,CAAC,UAAU,CAAC,CAAQ;gBAEf,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,SAAc;IAW/C,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,UAAU;IAU9D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAavC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAa1C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAepD,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;CAalD"}

package/dist/client.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tap = void 0;
+const common_1 = require("@atproto/common");
+const channel_1 = require("./channel");
+const types_1 = require("./types");
+const util_1 = require("./util");
+class Tap {
+    constructor(url, config = {}) {
+        Object.defineProperty(this, "url", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "adminPassword", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "authHeader", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        if (!url.startsWith('http://') && !url.startsWith('https://')) {
+            throw new Error('Invalid URL, expected http:// or https://');
+        }
+        this.url = url;
+        this.adminPassword = config.adminPassword;
+        if (this.adminPassword) {
+            this.authHeader = (0, util_1.formatAdminAuthHeader)(this.adminPassword);
+        }
+    }
+    getHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.authHeader) {
+            headers['Authorization'] = this.authHeader;
+        }
+        return headers;
+    }
+    channel(handler, opts) {
+        const url = new URL(this.url);
+        url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+        url.pathname = '/channel';
+        return new channel_1.TapChannel(url.toString(), handler, {
+            adminPassword: this.adminPassword,
+            ...opts,
+        });
+    }
+    async addRepos(dids) {
+        const response = await fetch(`${this.url}/repos/add`, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify({ dids }),
+        });
+        await response.body?.cancel(); // expect empty body
+        if (!response.ok) {
+            throw new Error(`Failed to add repos: ${response.statusText}`);
+        }
+    }
+    async removeRepos(dids) {
+        const response = await fetch(`${this.url}/repos/remove`, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify({ dids }),
+        });
+        await response.body?.cancel(); // expect empty body
+        if (!response.ok) {
+            throw new Error(`Failed to remove repos: ${response.statusText}`);
+        }
+    }
+    async resolveDid(did) {
+        const response = await fetch(`${this.url}/resolve/${did}`, {
+            method: 'GET',
+            headers: this.getHeaders(),
+        });
+        if (response.status === 404) {
+            return null;
+        }
+        else if (!response.ok) {
+            await response.body?.cancel();
+            throw new Error(`Failed to resolve DID: ${response.statusText}`);
+        }
+        return common_1.didDocument.parse(await response.json());
+    }
+    async getRepoInfo(did) {
+        const response = await fetch(`${this.url}/info/${did}`, {
+            method: 'GET',
+            headers: this.getHeaders(),
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new Error(`Failed to get repo info: ${response.statusText}`);
+        }
+        return types_1.repoInfoSchema.parse(await response.json());
+    }
+}
+exports.Tap = Tap;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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","sourcesContent":["import { DidDocument, didDocument } from '@atproto/common'\nimport { TapChannel, TapHandler, TapWebsocketOptions } from './channel'\nimport { RepoInfo, repoInfoSchema } from './types'\nimport { formatAdminAuthHeader } from './util'\n\nexport interface TapConfig {\n  adminPassword?: string\n}\n\nexport class Tap {\n  url: string\n  private adminPassword?: string\n  private authHeader?: string\n\n  constructor(url: string, config: TapConfig = {}) {\n    if (!url.startsWith('http://') && !url.startsWith('https://')) {\n      throw new Error('Invalid URL, expected http:// or https://')\n    }\n    this.url = url\n    this.adminPassword = config.adminPassword\n    if (this.adminPassword) {\n      this.authHeader = formatAdminAuthHeader(this.adminPassword)\n    }\n  }\n\n  private getHeaders(): Record<string, string> {\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n    }\n    if (this.authHeader) {\n      headers['Authorization'] = this.authHeader\n    }\n    return headers\n  }\n\n  channel(handler: TapHandler, opts?: TapWebsocketOptions): TapChannel {\n    const url = new URL(this.url)\n    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'\n    url.pathname = '/channel'\n    return new TapChannel(url.toString(), handler, {\n      adminPassword: this.adminPassword,\n      ...opts,\n    })\n  }\n\n  async addRepos(dids: string[]): Promise<void> {\n    const response = await fetch(`${this.url}/repos/add`, {\n      method: 'POST',\n      headers: this.getHeaders(),\n      body: JSON.stringify({ dids }),\n    })\n    await response.body?.cancel() // expect empty body\n\n    if (!response.ok) {\n      throw new Error(`Failed to add repos: ${response.statusText}`)\n    }\n  }\n\n  async removeRepos(dids: string[]): Promise<void> {\n    const response = await fetch(`${this.url}/repos/remove`, {\n      method: 'POST',\n      headers: this.getHeaders(),\n      body: JSON.stringify({ dids }),\n    })\n    await response.body?.cancel() // expect empty body\n\n    if (!response.ok) {\n      throw new Error(`Failed to remove repos: ${response.statusText}`)\n    }\n  }\n\n  async resolveDid(did: string): Promise<DidDocument | null> {\n    const response = await fetch(`${this.url}/resolve/${did}`, {\n      method: 'GET',\n      headers: this.getHeaders(),\n    })\n\n    if (response.status === 404) {\n      return null\n    } else if (!response.ok) {\n      await response.body?.cancel()\n      throw new Error(`Failed to resolve DID: ${response.statusText}`)\n    }\n    return didDocument.parse(await response.json())\n  }\n\n  async getRepoInfo(did: string): Promise<RepoInfo> {\n    const response = await fetch(`${this.url}/info/${did}`, {\n      method: 'GET',\n      headers: this.getHeaders(),\n    })\n\n    if (!response.ok) {\n      await response.body?.cancel()\n      throw new Error(`Failed to get repo info: ${response.statusText}`)\n    }\n\n    return repoInfoSchema.parse(await response.json())\n  }\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './client';
+export * from './channel';
+export * from './simple-indexer';
+export * from './util';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,cAAc,kBAAkB,CAAA;AAChC,cAAc,QAAQ,CAAA"}

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./client"), exports);
+__exportStar(require("./channel"), exports);
+__exportStar(require("./simple-indexer"), exports);
+__exportStar(require("./util"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAuB;AACvB,2CAAwB;AACxB,4CAAyB;AACzB,mDAAgC;AAChC,yCAAsB","sourcesContent":["export * from './types'\nexport * from './client'\nexport * from './channel'\nexport * from './simple-indexer'\nexport * from './util'\n"]}

package/dist/simple-indexer.d.ts

@@ -0,0 +1,17 @@
+import { HandlerOpts, TapHandler } from './channel';
+import { IdentityEvent, RecordEvent, TapEvent } from './types';
+type IdentityEventHandler = (evt: IdentityEvent, opts?: HandlerOpts) => Promise<void>;
+type RecordEventHandler = (evt: RecordEvent, opts?: HandlerOpts) => Promise<void>;
+type ErrorHandler = (err: Error) => void;
+export declare class SimpleIndexer implements TapHandler {
+    private identityHandler;
+    private recordHandler;
+    private errorHandler;
+    identity(fn: IdentityEventHandler): void;
+    record(fn: RecordEventHandler): void;
+    error(fn: ErrorHandler): void;
+    onEvent(evt: TapEvent, opts: HandlerOpts): Promise<void>;
+    onError(err: Error): void;
+}
+export {};
+//# sourceMappingURL=simple-indexer.d.ts.map

package/dist/simple-indexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-indexer.d.ts","sourceRoot":"","sources":["../src/simple-indexer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAE9D,KAAK,oBAAoB,GAAG,CAC1B,GAAG,EAAE,aAAa,EAClB,IAAI,CAAC,EAAE,WAAW,KACf,OAAO,CAAC,IAAI,CAAC,CAAA;AAClB,KAAK,kBAAkB,GAAG,CACxB,GAAG,EAAE,WAAW,EAChB,IAAI,CAAC,EAAE,WAAW,KACf,OAAO,CAAC,IAAI,CAAC,CAAA;AAClB,KAAK,YAAY,GAAG,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAA;AAExC,qBAAa,aAAc,YAAW,UAAU;IAC9C,OAAO,CAAC,eAAe,CAAkC;IACzD,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,YAAY,CAA0B;IAE9C,QAAQ,CAAC,EAAE,EAAE,oBAAoB;IAIjC,MAAM,CAAC,EAAE,EAAE,kBAAkB;IAI7B,KAAK,CAAC,EAAE,EAAE,YAAY;IAIhB,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9D,OAAO,CAAC,GAAG,EAAE,KAAK;CAOnB"}