@pgns/core 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PGNS LLC
+
+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,238 @@
+# @pgns/core
+
+TypeScript SDK for the pgns API. Framework-agnostic — works in Node.js, Deno, Bun, edge runtimes, and the browser.
+
+## Install
+
+```bash
+npm install @pgns/core
+# or
+pnpm add @pgns/core
+```
+
+## Quick Start
+
+### With an API key (server-side)
+
+```ts
+import { PigeonsClient } from "@pgns/core";
+
+const client = new PigeonsClient({
+  baseUrl: "https://api.pgns.io",
+  apiKey: "pk_live_...",
+});
+
+const roosts = await client.listRoosts();
+```
+
+### With user authentication (browser)
+
+```ts
+import { PigeonsClient } from "@pgns/core";
+
+const client = new PigeonsClient({
+  baseUrl: "https://api.pgns.io",
+  onTokenRefresh(tokens) {
+    // Persist new tokens however you like
+    localStorage.setItem("access_token", tokens.access_token);
+    localStorage.setItem("refresh_token", tokens.refresh_token);
+  },
+});
+
+await client.login({ email: "user@example.com", password: "..." });
+const roosts = await client.listRoosts();
+```
+
+## Authentication
+
+The client supports two authentication modes:
+
+| Mode | Use case | How |
+|------|----------|-----|
+| **API key** | Server-side / scripts | Pass `apiKey` to the constructor |
+| **JWT** | Browser / user sessions | Call `login()` / `signup()`, or pass `accessToken` to the constructor |
+
+When using JWT auth the client automatically retries on `401` by refreshing the token. Supply `onTokenRefresh` to persist new tokens.
+
+You can switch credentials at any time:
+
+```ts
+client.setApiKey("pk_live_new_key");
+// or
+client.setAccessToken("eyJhbG...");
+```
+
+## Roosts
+
+Roosts are webhook endpoints that receive incoming requests and route them to destinations.
+
+```ts
+// Create
+const roost = await client.createRoost({
+  name: "GitHub Webhooks",
+  description: "Receives push events",
+  secret: "whsec_...",       // optional HMAC verification secret
+});
+
+// List all
+const roosts = await client.listRoosts();
+
+// Get by ID
+const roost = await client.getRoost("rst_01J...");
+
+// Update
+await client.updateRoost("rst_01J...", { name: "Renamed" });
+
+// Delete
+await client.deleteRoost("rst_01J...");
+```
+
+## Pigeons
+
+Pigeons are individual webhook requests captured by a roost.
+
+```ts
+// List pigeons for a roost (default limit: 50)
+const pigeons = await client.listPigeons({ roostId: "rst_01J..." });
+
+// List all pigeons across roosts
+const all = await client.listPigeons();
+
+// With custom limit
+const recent = await client.listPigeons({ roostId: "rst_01J...", limit: 10 });
+
+// Get a single pigeon
+const pigeon = await client.getPigeon("pgn_01J...");
+
+// Get delivery attempts for a pigeon
+const deliveries = await client.getPigeonDeliveries("pgn_01J...");
+
+// Replay a pigeon (re-deliver to all destinations)
+const result = await client.replayPigeon("pgn_01J...");
+// => { replayed: true, pigeon_id: "pgn_01J...", delivery_attempts: 2 }
+```
+
+## Destinations
+
+Destinations define where pigeons get forwarded to — URLs, Slack, Discord, or email.
+
+```ts
+// Create a URL destination
+const dest = await client.createDestination("rst_01J...", {
+  destination_type: "url",
+  config: { url: "https://example.com/webhook" },
+  filter_expression: "headers.x-event == 'push'",  // optional CEL filter
+  retry_max: 3,
+  retry_delay_ms: 1000,
+  retry_multiplier: 2,
+});
+
+// List destinations for a roost
+const destinations = await client.listDestinations("rst_01J...");
+
+// Get by ID
+const dest = await client.getDestination("dst_01J...");
+
+// Pause / unpause
+await client.pauseDestination("dst_01J...", true);   // pause
+await client.pauseDestination("dst_01J...", false);  // unpause
+
+// Delete
+await client.deleteDestination("dst_01J...");
+```
+
+### Destination types
+
+| Type | Config |
+|------|--------|
+| `url` | `{ url: string }` |
+| `slack` | `{ webhook_url: string }` |
+| `discord` | `{ webhook_url: string }` |
+| `email` | `{ to: string }` |
+
+## API Keys
+
+Manage API keys for programmatic access.
+
+```ts
+// Create (name is optional)
+const created = await client.createApiKey({ name: "CI deploy key" });
+// => { id: "...", key: "pk_live_...", key_prefix: "pk_live_abc", name: "CI deploy key", created_at: "..." }
+// The full key is only returned at creation time — store it securely.
+
+// List
+const keys = await client.listApiKeys();
+
+// Get
+const key = await client.getApiKey("key_01J...");
+
+// Rename
+await client.updateApiKey("key_01J...", { name: "Renamed key" });
+
+// Revoke
+await client.deleteApiKey("key_01J...");
+```
+
+## Real-time Events (SSE)
+
+Subscribe to a live stream of incoming pigeons using Server-Sent Events. Works in any runtime with `fetch` and `ReadableStream`.
+
+```ts
+import { createEventSource } from "@pgns/core";
+
+const controller = new AbortController();
+
+createEventSource("https://api.pgns.io", {
+  token: "eyJhbG...",
+  roostId: "rst_01J...",            // optional — omit for all roosts
+  signal: controller.signal,
+  onEvent(data) {
+    console.log("New pigeon:", data);
+  },
+  onError(err) {
+    console.error("SSE error:", err);
+  },
+});
+
+// Stop listening
+controller.abort();
+```
+
+The connection automatically reconnects on failure with a 3-second delay.
+
+## Error Handling
+
+All API errors throw a `PigeonsError` with the HTTP status code attached.
+
+```ts
+import { PigeonsClient, PigeonsError } from "@pgns/core";
+
+try {
+  await client.getRoost("rst_nonexistent");
+} catch (err) {
+  if (err instanceof PigeonsError) {
+    console.error(err.message); // "Not found"
+    console.error(err.status);  // 404
+  }
+}
+```
+
+## Zod Schemas
+
+Every type has a corresponding Zod schema exported for runtime validation. Useful for validating webhook payloads or API responses in your own code.
+
+```ts
+import { PigeonSchema, RoostSchema } from "@pgns/core";
+
+const parsed = PigeonSchema.parse(untrustedData);
+```
+
+Available schemas: `AuthTokensSchema`, `UserSchema`, `RoostSchema`, `PigeonSchema`, `DestinationSchema`, `DeliveryAttemptSchema`, `ApiKeyResponseSchema`, `ApiKeyCreatedResponseSchema`, `CreateRoostSchema`, `UpdateRoostSchema`, `CreateDestinationSchema`, `CreateApiKeyRequestSchema`, `UpdateApiKeyRequestSchema`, `ReplayResponseSchema`, `ApiErrorSchema`, `DestinationTypeSchema`, `DeliveryStatusSchema`.
+
+## TypeScript
+
+All types are exported and inferred from the Zod schemas:
+
+```ts
+import type { Roost, Pigeon, Destination, DeliveryAttempt } from "@pgns/core";
+```

package/dist/client.d.ts

@@ -0,0 +1,108 @@
+import type { ApiKeyCreatedResponse, ApiKeyResponse, AuthTokens, CreateApiKeyRequest, CreateDestination, CreateRoost, DeliveryAttempt, Destination, LoginRequest, MagicLinkRequest, MagicLinkVerifyRequest, Pigeon, ReplayResponse, Roost, SignupRequest, UpdateApiKeyRequest, UpdateRoost } from './types.js';
+/** Configuration for {@link PigeonsClient}. */
+export interface PigeonsClientConfig {
+    /** Base URL of the pgns API (e.g. `"https://api.pgns.io"`). */
+    baseUrl: string;
+    /** API key (`pk_live_...`) for server-side authentication. */
+    apiKey?: string;
+    /** JWT access token for browser / user-session authentication. */
+    accessToken?: string;
+    /** Called after a token refresh so you can persist the new tokens. */
+    onTokenRefresh?: (tokens: AuthTokens) => void;
+}
+/**
+ * Framework-agnostic client for the pgns API.
+ *
+ * Supports two authentication modes:
+ * - **API key** — pass `apiKey` in the constructor for server-side usage.
+ * - **JWT** — call {@link login} / {@link signup}, or pass `accessToken`.
+ *   Expired tokens are refreshed automatically on `401`.
+ *
+ * @example
+ * ```ts
+ * const client = new PigeonsClient({
+ *   baseUrl: "https://api.pgns.io",
+ *   apiKey: "pk_live_...",
+ * });
+ * const roosts = await client.listRoosts();
+ * ```
+ */
+export declare class PigeonsClient {
+    private baseUrl;
+    private apiKey?;
+    private accessToken?;
+    private onTokenRefresh?;
+    private refreshPromise;
+    constructor(config: PigeonsClientConfig);
+    /** Replace the current JWT access token. */
+    setAccessToken(token: string): void;
+    /** Replace the current API key. */
+    setApiKey(key: string): void;
+    private authHeader;
+    private handleResponse;
+    /** Coalesce concurrent refresh calls into a single request. */
+    private refreshToken;
+    private request;
+    private unauthRequest;
+    /** Create a new account. Stores the returned tokens on the client. */
+    signup(data: SignupRequest): Promise<AuthTokens>;
+    /** Authenticate with email and password. Stores the returned tokens on the client. */
+    login(data: LoginRequest): Promise<AuthTokens>;
+    /** Send a magic-link email to the given address. */
+    requestMagicLink(data: MagicLinkRequest): Promise<{
+        message: string;
+    }>;
+    /** Exchange a magic-link token for auth tokens. Stores the returned tokens on the client. */
+    verifyMagicLink(data: MagicLinkVerifyRequest): Promise<AuthTokens>;
+    /** Refresh the access token. The refresh token is sent via httpOnly cookie. */
+    refresh(): Promise<AuthTokens>;
+    /** Revoke the refresh token (via cookie) and clear stored credentials on the client. */
+    logout(): Promise<void>;
+    /** List all roosts for the authenticated user. */
+    listRoosts(): Promise<Roost[]>;
+    /** Get a roost by ID. */
+    getRoost(roostId: string): Promise<Roost>;
+    /** Create a new roost (webhook endpoint). */
+    createRoost(data: CreateRoost): Promise<Roost>;
+    /** Update a roost's name, description, secret, or active state. */
+    updateRoost(roostId: string, data: UpdateRoost): Promise<Roost>;
+    /** Delete a roost and all its destinations. */
+    deleteRoost(roostId: string): Promise<void>;
+    /**
+     * List pigeons, optionally filtered by roost.
+     * @param opts.roostId - Restrict results to a single roost. Omit for all roosts.
+     * @param opts.limit - Maximum number of results (default: 50).
+     */
+    listPigeons(opts?: {
+        roostId?: string;
+        limit?: number;
+    }): Promise<Pigeon[]>;
+    /** Get a single pigeon by ID, including headers and body. */
+    getPigeon(pigeonId: string): Promise<Pigeon>;
+    /** List all delivery attempts for a pigeon. */
+    getPigeonDeliveries(pigeonId: string): Promise<DeliveryAttempt[]>;
+    /** Re-deliver a pigeon to all active destinations. */
+    replayPigeon(pigeonId: string): Promise<ReplayResponse>;
+    /** List all destinations for a roost. */
+    listDestinations(roostId: string): Promise<Destination[]>;
+    /** Get a destination by ID. */
+    getDestination(destinationId: string): Promise<Destination>;
+    /** Add a new destination (url, slack, discord, or email) to a roost. */
+    createDestination(roostId: string, data: CreateDestination): Promise<Destination>;
+    /** Pause or unpause delivery to a destination. */
+    pauseDestination(destinationId: string, isPaused: boolean): Promise<{
+        is_paused: boolean;
+    }>;
+    /** Permanently delete a destination. */
+    deleteDestination(destinationId: string): Promise<void>;
+    /** List all API keys for the authenticated user. */
+    listApiKeys(): Promise<ApiKeyResponse[]>;
+    /** Get an API key by ID. Does not return the full key value. */
+    getApiKey(keyId: string): Promise<ApiKeyResponse>;
+    /** Create a new API key. The full key is only returned in this response — store it securely. */
+    createApiKey(data?: CreateApiKeyRequest): Promise<ApiKeyCreatedResponse>;
+    /** Rename an API key. */
+    updateApiKey(keyId: string, data: UpdateApiKeyRequest): Promise<ApiKeyResponse>;
+    /** Permanently revoke and delete an API key. */
+    deleteApiKey(keyId: string): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,278 @@
+import { PigeonsError } from './errors.js';
+/**
+ * Framework-agnostic client for the pgns API.
+ *
+ * Supports two authentication modes:
+ * - **API key** — pass `apiKey` in the constructor for server-side usage.
+ * - **JWT** — call {@link login} / {@link signup}, or pass `accessToken`.
+ *   Expired tokens are refreshed automatically on `401`.
+ *
+ * @example
+ * ```ts
+ * const client = new PigeonsClient({
+ *   baseUrl: "https://api.pgns.io",
+ *   apiKey: "pk_live_...",
+ * });
+ * const roosts = await client.listRoosts();
+ * ```
+ */
+export class PigeonsClient {
+    baseUrl;
+    apiKey;
+    accessToken;
+    onTokenRefresh;
+    refreshPromise = null;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.apiKey = config.apiKey;
+        this.accessToken = config.accessToken;
+        this.onTokenRefresh = config.onTokenRefresh;
+    }
+    /** Replace the current JWT access token. */
+    setAccessToken(token) {
+        this.accessToken = token;
+    }
+    /** Replace the current API key. */
+    setApiKey(key) {
+        this.apiKey = key;
+    }
+    // -- Internal helpers --
+    authHeader() {
+        if (this.apiKey)
+            return { Authorization: `Bearer ${this.apiKey}` };
+        if (this.accessToken)
+            return { Authorization: `Bearer ${this.accessToken}` };
+        return {};
+    }
+    async handleResponse(res) {
+        if (!res.ok) {
+            const body = (await res.json().catch(() => ({ error: res.statusText })));
+            throw new PigeonsError(body.error, res.status);
+        }
+        if (res.status === 204)
+            return undefined;
+        return res.json();
+    }
+    /** Coalesce concurrent refresh calls into a single request. */
+    async refreshToken() {
+        if (this.refreshPromise)
+            return this.refreshPromise;
+        this.refreshPromise = this.unauthRequest('/v1/auth/refresh', {
+            method: 'POST',
+        }).finally(() => {
+            this.refreshPromise = null;
+        });
+        const tokens = await this.refreshPromise;
+        this.accessToken = tokens.access_token;
+        this.onTokenRefresh?.(tokens);
+        return tokens;
+    }
+    async request(path, options = {}) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            ...options,
+            credentials: 'include',
+            headers: {
+                'Content-Type': 'application/json',
+                ...this.authHeader(),
+                ...options.headers,
+            },
+        });
+        if (res.status === 401 && !this.apiKey) {
+            try {
+                const tokens = await this.refreshToken();
+                const retryRes = await fetch(`${this.baseUrl}${path}`, {
+                    ...options,
+                    credentials: 'include',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${tokens.access_token}`,
+                        ...options.headers,
+                    },
+                });
+                return this.handleResponse(retryRes);
+            }
+            catch (err) {
+                this.accessToken = undefined;
+                throw new PigeonsError('Session expired', 401, err);
+            }
+        }
+        return this.handleResponse(res);
+    }
+    async unauthRequest(path, options = {}) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            ...options,
+            credentials: 'include',
+            headers: {
+                'Content-Type': 'application/json',
+                ...options.headers,
+            },
+        });
+        return this.handleResponse(res);
+    }
+    // -- Auth --
+    /** Create a new account. Stores the returned tokens on the client. */
+    async signup(data) {
+        const tokens = await this.unauthRequest('/v1/auth/signup', {
+            method: 'POST',
+            body: JSON.stringify(data),
+        });
+        this.accessToken = tokens.access_token;
+        this.onTokenRefresh?.(tokens);
+        return tokens;
+    }
+    /** Authenticate with email and password. Stores the returned tokens on the client. */
+    async login(data) {
+        const tokens = await this.unauthRequest('/v1/auth/login', {
+            method: 'POST',
+            body: JSON.stringify(data),
+        });
+        this.accessToken = tokens.access_token;
+        this.onTokenRefresh?.(tokens);
+        return tokens;
+    }
+    /** Send a magic-link email to the given address. */
+    async requestMagicLink(data) {
+        return this.unauthRequest('/v1/auth/magic-link', {
+            method: 'POST',
+            body: JSON.stringify(data),
+        });
+    }
+    /** Exchange a magic-link token for auth tokens. Stores the returned tokens on the client. */
+    async verifyMagicLink(data) {
+        const tokens = await this.unauthRequest('/v1/auth/magic-link/verify', {
+            method: 'POST',
+            body: JSON.stringify(data),
+        });
+        this.accessToken = tokens.access_token;
+        this.onTokenRefresh?.(tokens);
+        return tokens;
+    }
+    /** Refresh the access token. The refresh token is sent via httpOnly cookie. */
+    async refresh() {
+        const tokens = await this.unauthRequest('/v1/auth/refresh', {
+            method: 'POST',
+        });
+        this.accessToken = tokens.access_token;
+        this.onTokenRefresh?.(tokens);
+        return tokens;
+    }
+    /** Revoke the refresh token (via cookie) and clear stored credentials on the client. */
+    async logout() {
+        await this.request('/v1/auth/logout', {
+            method: 'POST',
+        });
+        this.accessToken = undefined;
+    }
+    // -- Roosts --
+    /** List all roosts for the authenticated user. */
+    listRoosts() {
+        return this.request('/v1/roosts');
+    }
+    /** Get a roost by ID. */
+    getRoost(roostId) {
+        return this.request(`/v1/roosts/${encodeURIComponent(roostId)}`);
+    }
+    /** Create a new roost (webhook endpoint). */
+    createRoost(data) {
+        return this.request('/v1/roosts', {
+            method: 'POST',
+            body: JSON.stringify(data),
+        });
+    }
+    /** Update a roost's name, description, secret, or active state. */
+    updateRoost(roostId, data) {
+        return this.request(`/v1/roosts/${encodeURIComponent(roostId)}`, {
+            method: 'PATCH',
+            body: JSON.stringify(data),
+        });
+    }
+    /** Delete a roost and all its destinations. */
+    deleteRoost(roostId) {
+        return this.request(`/v1/roosts/${encodeURIComponent(roostId)}`, { method: 'DELETE' });
+    }
+    // -- Pigeons --
+    /**
+     * List pigeons, optionally filtered by roost.
+     * @param opts.roostId - Restrict results to a single roost. Omit for all roosts.
+     * @param opts.limit - Maximum number of results (default: 50).
+     */
+    listPigeons(opts) {
+        const params = new URLSearchParams();
+        if (opts?.roostId)
+            params.set('roost_id', opts.roostId);
+        params.set('limit', String(opts?.limit ?? 50));
+        return this.request(`/v1/pigeons?${params.toString()}`);
+    }
+    /** Get a single pigeon by ID, including headers and body. */
+    getPigeon(pigeonId) {
+        return this.request(`/v1/pigeons/${encodeURIComponent(pigeonId)}`);
+    }
+    /** List all delivery attempts for a pigeon. */
+    getPigeonDeliveries(pigeonId) {
+        return this.request(`/v1/pigeons/${encodeURIComponent(pigeonId)}/deliveries`);
+    }
+    /** Re-deliver a pigeon to all active destinations. */
+    replayPigeon(pigeonId) {
+        return this.request(`/v1/pigeons/${encodeURIComponent(pigeonId)}/replay`, {
+            method: 'POST',
+        });
+    }
+    // -- Destinations --
+    /** List all destinations for a roost. */
+    listDestinations(roostId) {
+        return this.request(`/v1/roosts/${encodeURIComponent(roostId)}/destinations`);
+    }
+    /** Get a destination by ID. */
+    getDestination(destinationId) {
+        return this.request(`/v1/destinations/${encodeURIComponent(destinationId)}`);
+    }
+    /** Add a new destination (url, slack, discord, or email) to a roost. */
+    createDestination(roostId, data) {
+        return this.request(`/v1/roosts/${encodeURIComponent(roostId)}/destinations`, {
+            method: 'POST',
+            body: JSON.stringify(data),
+        });
+    }
+    /** Pause or unpause delivery to a destination. */
+    pauseDestination(destinationId, isPaused) {
+        return this.request(`/v1/destinations/${encodeURIComponent(destinationId)}/pause`, {
+            method: 'PATCH',
+            body: JSON.stringify({ is_paused: isPaused }),
+        });
+    }
+    /** Permanently delete a destination. */
+    deleteDestination(destinationId) {
+        return this.request(`/v1/destinations/${encodeURIComponent(destinationId)}`, {
+            method: 'DELETE',
+        });
+    }
+    // -- API Keys --
+    /** List all API keys for the authenticated user. */
+    listApiKeys() {
+        return this.request('/v1/api-keys');
+    }
+    /** Get an API key by ID. Does not return the full key value. */
+    getApiKey(keyId) {
+        return this.request(`/v1/api-keys/${encodeURIComponent(keyId)}`);
+    }
+    /** Create a new API key. The full key is only returned in this response — store it securely. */
+    createApiKey(data = {}) {
+        return this.request('/v1/api-keys', {
+            method: 'POST',
+            body: JSON.stringify(data),
+        });
+    }
+    /** Rename an API key. */
+    updateApiKey(keyId, data) {
+        return this.request(`/v1/api-keys/${encodeURIComponent(keyId)}`, {
+            method: 'PATCH',
+            body: JSON.stringify(data),
+        });
+    }
+    /** Permanently revoke and delete an API key. */
+    deleteApiKey(keyId) {
+        return this.request(`/v1/api-keys/${encodeURIComponent(keyId)}`, {
+            method: 'DELETE',
+        });
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+/** Error thrown by {@link PigeonsClient} when the API returns a non-2xx response. */
+export declare class PigeonsError extends Error {
+    /** HTTP status code from the API response. */
+    status: number;
+    constructor(message: string, status: number, cause?: unknown);
+}

package/dist/errors.js

@@ -0,0 +1,10 @@
+/** Error thrown by {@link PigeonsClient} when the API returns a non-2xx response. */
+export class PigeonsError extends Error {
+    /** HTTP status code from the API response. */
+    status;
+    constructor(message, status, cause) {
+        super(message, cause !== undefined ? { cause } : undefined);
+        this.name = 'PigeonsError';
+        this.status = status;
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,31 @@
+/** Options for {@link createEventSource}. */
+export interface EventSourceOptions {
+    /** Bearer token for authentication. */
+    token?: string;
+    /** Restrict the stream to pigeons for a single roost. Omit for all roosts. */
+    roostId?: string;
+    /** Abort signal to stop the connection. */
+    signal?: AbortSignal;
+    /** Called for each SSE `data:` line received. */
+    onEvent: (data: string) => void;
+    /** Called when a connection error occurs (before automatic reconnect). */
+    onError?: (err: Error) => void;
+}
+/**
+ * Connect to the Pgns SSE event stream using `fetch` + `ReadableStream`.
+ *
+ * Automatically reconnects on failure with a 3-second delay. Cancel the
+ * connection by aborting the signal passed in `opts`.
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController();
+ * createEventSource("https://api.pgns.io", {
+ *   token: "eyJhbG...",
+ *   signal: controller.signal,
+ *   onEvent(data) { console.log(data); },
+ * });
+ * // later: controller.abort();
+ * ```
+ */
+export declare function createEventSource(baseUrl: string, opts: EventSourceOptions): Promise<void>;