@zooid/sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zooid-ai
+
+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/dist/index.cjs

@@ -0,0 +1,351 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ZooidClient: () => ZooidClient,
+  ZooidError: () => ZooidError,
+  verifyWebhook: () => verifyWebhook
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/error.ts
+var ZooidError = class extends Error {
+  /** HTTP status code from the server response. */
+  status;
+  constructor(status, message) {
+    super(message);
+    this.name = "ZooidError";
+    this.status = status;
+  }
+};
+
+// src/client.ts
+var ZooidClient = class {
+  /** Base URL of the Zooid server (trailing slashes stripped). */
+  server;
+  token;
+  _fetch;
+  constructor(options) {
+    this.server = options.server.replace(/\/+$/, "");
+    this.token = options.token;
+    this._fetch = options.fetch ?? globalThis.fetch;
+  }
+  async request(method, path, body) {
+    const headers = {};
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    const res = await this._fetch(this.server + path, {
+      method,
+      headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      let message = `HTTP ${res.status}`;
+      try {
+        const json = await res.json();
+        if (json.error) message = String(json.error);
+      } catch {
+      }
+      throw new ZooidError(res.status, message);
+    }
+    if (res.status === 204) {
+      return void 0;
+    }
+    return res.json();
+  }
+  /** Fetch server discovery metadata from `GET /.well-known/zooid.json`. */
+  async getMetadata() {
+    return this.request("GET", "/.well-known/zooid.json");
+  }
+  /** Fetch editable server identity from `GET /api/v1/server`. */
+  async getServerMeta() {
+    return this.request("GET", "/api/v1/server");
+  }
+  /** Update server identity metadata via `PUT /api/v1/server`. Requires admin token. */
+  async updateServerMeta(options) {
+    return this.request("PUT", "/api/v1/server", options);
+  }
+  /** List all channels via `GET /api/v1/channels`. */
+  async listChannels() {
+    const res = await this.request("GET", "/api/v1/channels");
+    return res.channels;
+  }
+  /** Create a new channel via `POST /api/v1/channels`. Requires admin token. */
+  async createChannel(options) {
+    return this.request("POST", "/api/v1/channels", options);
+  }
+  /** Generate a signed claim for the Zooid Directory. Requires admin token. */
+  async getClaim(channels, action) {
+    const body = { channels };
+    if (action) body.action = action;
+    return this.request("POST", "/api/v1/directory/claim", body);
+  }
+  /** Add a named publisher to a channel. Requires admin token. */
+  async addPublisher(channelId, name) {
+    return this.request(
+      "POST",
+      `/api/v1/channels/${channelId}/publishers`,
+      { name }
+    );
+  }
+  /** Publish a single event to a channel. Requires a publish-scoped token. */
+  async publish(channelId, options) {
+    const body = { data: options.data };
+    if (options.type !== void 0) {
+      body.type = options.type;
+    }
+    return this.request("POST", `/api/v1/channels/${channelId}/events`, body);
+  }
+  /** Publish multiple events in a single request. Requires a publish-scoped token. */
+  async publishBatch(channelId, events) {
+    const body = {
+      events: events.map((e) => {
+        const item = { data: e.data };
+        if (e.type !== void 0) item.type = e.type;
+        return item;
+      })
+    };
+    const res = await this.request(
+      "POST",
+      `/api/v1/channels/${channelId}/events`,
+      body
+    );
+    return res.events;
+  }
+  tail(channelId, options) {
+    if (options?.follow) {
+      return this.createTailStream(channelId, options);
+    }
+    return this.poll(channelId, options);
+  }
+  createTailStream(channelId, options) {
+    const buffer = [];
+    let waiting = null;
+    let done = false;
+    let unsub = null;
+    this.subscribe(channelId, (event) => {
+      if (waiting) {
+        const resolve = waiting;
+        waiting = null;
+        resolve({ value: event, done: false });
+      } else {
+        buffer.push(event);
+      }
+    }, {
+      mode: options.mode,
+      interval: options.interval,
+      type: options.type
+    }).then((fn) => {
+      unsub = fn;
+      if (done) fn();
+    });
+    const stream = {
+      close() {
+        done = true;
+        unsub?.();
+        if (waiting) {
+          waiting({ value: void 0, done: true });
+          waiting = null;
+        }
+      },
+      [Symbol.asyncIterator]() {
+        return {
+          next() {
+            if (buffer.length > 0) {
+              return Promise.resolve({ value: buffer.shift(), done: false });
+            }
+            if (done) {
+              return Promise.resolve({ value: void 0, done: true });
+            }
+            return new Promise((resolve) => {
+              waiting = resolve;
+            });
+          },
+          return() {
+            stream.close();
+            return Promise.resolve({ value: void 0, done: true });
+          }
+        };
+      }
+    };
+    return stream;
+  }
+  /** Poll events from a channel with cursor-based pagination. */
+  async poll(channelId, options) {
+    const params = new URLSearchParams();
+    if (options?.cursor) params.set("cursor", options.cursor);
+    if (options?.limit !== void 0) params.set("limit", String(options.limit));
+    if (options?.type) params.set("type", options.type);
+    if (options?.since) params.set("since", options.since);
+    const qs = params.toString();
+    const path = `/api/v1/channels/${channelId}/events${qs ? `?${qs}` : ""}`;
+    return this.request("GET", path);
+  }
+  /** Register a webhook to receive events via POST. */
+  async registerWebhook(channelId, url, options) {
+    return this.request("POST", `/api/v1/channels/${channelId}/webhooks`, {
+      url,
+      ...options
+    });
+  }
+  /** Remove a webhook registration. Requires admin token. */
+  async removeWebhook(channelId, webhookId) {
+    await this.request(
+      "DELETE",
+      `/api/v1/channels/${channelId}/webhooks/${webhookId}`
+    );
+  }
+  /**
+   * Subscribe to a channel. Tries WebSocket first (mode `'auto'`), falls back to polling.
+   *
+   * Returns a promise that resolves with an unsubscribe function.
+   *
+   * @example
+   * ```ts
+   * const unsub = await client.subscribe('my-channel', (event) => {
+   *   console.log('New event:', event.id);
+   * });
+   *
+   * // Later: stop
+   * unsub();
+   * ```
+   */
+  async subscribe(channelId, callback, options) {
+    const mode = options?.mode ?? "auto";
+    if (mode === "poll") {
+      return this.startPolling(channelId, callback, options);
+    }
+    const tryWs = (retryOnFail) => {
+      return new Promise((resolve, reject) => {
+        const url = this.buildWsUrl(channelId, options);
+        const ws = new globalThis.WebSocket(url);
+        ws.onopen = () => {
+          resolve(() => {
+            ws.close();
+          });
+        };
+        ws.onmessage = (e) => {
+          try {
+            const event = JSON.parse(String(e.data));
+            callback(event);
+          } catch {
+          }
+        };
+        ws.onclose = () => {
+        };
+        ws.onerror = () => {
+          ws.close();
+          if (retryOnFail) {
+            setTimeout(() => {
+              tryWs(false).then(resolve, reject);
+            }, 1e3);
+          } else if (mode === "auto") {
+            this.startPolling(channelId, callback, options).then(resolve, reject);
+          } else {
+            reject(new Error("WebSocket connection failed"));
+          }
+        };
+      });
+    };
+    return tryWs(true);
+  }
+  buildWsUrl(channelId, options) {
+    const base = this.server.replace(/^http:\/\//, "ws://").replace(/^https:\/\//, "wss://");
+    const params = new URLSearchParams();
+    if (this.token) params.set("token", this.token);
+    if (options?.type) params.set("types", options.type);
+    const qs = params.toString();
+    return `${base}/api/v1/channels/${channelId}/ws${qs ? `?${qs}` : ""}`;
+  }
+  startPolling(channelId, callback, options) {
+    const interval = options?.interval ?? 5e3;
+    const type = options?.type;
+    let cursor = null;
+    let timer = null;
+    let stopped = false;
+    const doPoll = async () => {
+      try {
+        const pollOpts = {};
+        if (cursor) pollOpts.cursor = cursor;
+        if (type) pollOpts.type = type;
+        const result = await this.poll(channelId, pollOpts);
+        if (stopped) return;
+        for (const event of result.events) {
+          callback(event);
+        }
+        if (result.cursor) {
+          cursor = result.cursor;
+        }
+      } catch {
+      }
+    };
+    doPoll();
+    timer = setInterval(doPoll, interval);
+    return Promise.resolve(() => {
+      stopped = true;
+      if (timer !== null) {
+        clearInterval(timer);
+        timer = null;
+      }
+    });
+  }
+};
+
+// src/verify.ts
+async function verifyWebhook(options) {
+  const { body, signature, timestamp, publicKey, maxAge } = options;
+  if (maxAge !== void 0) {
+    const ts = Date.parse(timestamp);
+    if (Number.isNaN(ts)) return false;
+    const age = (Date.now() - ts) / 1e3;
+    if (age > maxAge || age < -maxAge) return false;
+  }
+  const key = await crypto.subtle.importKey(
+    "spki",
+    base64ToArrayBuffer(publicKey),
+    "Ed25519",
+    false,
+    ["verify"]
+  );
+  const message = new TextEncoder().encode(`${timestamp}.${body}`);
+  const sigBytes = base64ToArrayBuffer(signature);
+  return crypto.subtle.verify("Ed25519", key, sigBytes, message);
+}
+function base64ToArrayBuffer(input) {
+  const base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ZooidClient,
+  ZooidError,
+  verifyWebhook
+});

package/dist/index.d.cts

@@ -0,0 +1,260 @@
+import { ChannelListItem, ZooidEvent as ZooidEvent$1, Webhook, ServerDiscovery, ServerIdentity, PollResult } from '@zooid/types';
+export { PollResult, ServerDiscovery, ServerIdentity, ServerMeta, ServerMetadata, ZooidEvent } from '@zooid/types';
+
+type ZooidEvent = ZooidEvent$1;
+/** Channel info as returned by `GET /api/v1/channels`. Alias for {@link ChannelListItem}. */
+type ChannelInfo = ChannelListItem;
+/** Webhook registration result. Alias for {@link Webhook}. */
+type WebhookResult = Webhook;
+/** Options for constructing a {@link ZooidClient}. */
+interface ZooidClientOptions {
+    /** Base URL of the Zooid server (e.g. `"https://zooid.example.workers.dev"`). */
+    server: string;
+    /** JWT token (admin, publish, or subscribe scoped). */
+    token?: string;
+    /** Custom fetch implementation (for testing or custom environments). */
+    fetch?: typeof globalThis.fetch;
+}
+/** Options for creating a new channel via `POST /api/v1/channels`. */
+interface CreateChannelOptions {
+    /** URL-safe slug identifier (lowercase + hyphens, 3-64 chars). */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Optional channel description. */
+    description?: string;
+    /** Whether the channel is publicly accessible. Defaults to `true`. */
+    is_public?: boolean;
+    /** Optional JSON Schema for event payload validation. */
+    schema?: Record<string, unknown>;
+    /** When `true`, events are rejected if they don't match `schema`. */
+    strict?: boolean;
+}
+/** Result of creating a new channel. */
+interface CreateChannelResult {
+    /** The channel's slug identifier. */
+    id: string;
+    /** JWT token scoped for publishing to this channel. */
+    publish_token: string;
+    /** JWT token scoped for subscribing to this channel. */
+    subscribe_token: string;
+}
+/** Result of adding a publisher to a channel. */
+interface PublisherResult {
+    /** ULID identifier for the new publisher. */
+    id: string;
+    /** Display name of the publisher. */
+    name: string;
+    /** JWT token scoped for publishing as this publisher. */
+    publish_token: string;
+}
+/** Options for publishing a single event. */
+interface PublishOptions {
+    /** Optional event type string for subscriber filtering. */
+    type?: string;
+    /** Event payload (will be JSON-serialized, max 64 KB). */
+    data: unknown;
+}
+/** Options for polling events from a channel. */
+interface PollOptions {
+    /** Opaque cursor from a previous poll response. */
+    cursor?: string;
+    /** ISO 8601 timestamp — only return events created after this time. */
+    since?: string;
+    /** Maximum number of events to return (default: 50). */
+    limit?: number;
+    /** Filter events by type. */
+    type?: string;
+}
+/** Options for registering a webhook. */
+interface WebhookOptions {
+    /** Only deliver events matching these types. Omit for all events. */
+    event_types?: string[];
+    /** Webhook lifetime in seconds (default: 3 days, max: 30 days). */
+    ttl_seconds?: number;
+}
+/** Subscribe transport mode. */
+type SubscribeMode = 'auto' | 'ws' | 'poll';
+/** Options for the subscribe helper. */
+interface SubscribeOptions {
+    /** Polling interval in milliseconds. Default: `5000`. */
+    interval?: number;
+    /** Transport mode. `'auto'` (default) tries WebSocket first, falls back to polling. */
+    mode?: SubscribeMode;
+    /** Event type filter — passed as `?types=` on WS, `?type=` on poll. */
+    type?: string;
+}
+/** Options for the `tail()` method. Extends poll options with follow mode. */
+interface TailOptions extends PollOptions {
+    /** When `true`, subscribe and stream events as they arrive. */
+    follow?: boolean;
+    /** Transport mode for follow mode. Default: `'auto'`. */
+    mode?: SubscribeMode;
+    /** Polling interval in ms for follow mode (poll transport). Default: `5000`. */
+    interval?: number;
+}
+/**
+ * An async iterable stream of events returned by `tail({ follow: true })`.
+ * Call `close()` to stop the underlying subscription and end the stream.
+ */
+interface TailStream extends AsyncIterable<ZooidEvent> {
+    /** Stop the subscription and end the stream. */
+    close(): void;
+}
+/** Result of generating a signed directory claim. */
+interface ClaimResult {
+    /** Base64url-encoded JSON claim payload. */
+    claim: string;
+    /** Base64url-encoded Ed25519 signature of the claim. */
+    signature: string;
+}
+/** Options for updating server identity metadata. */
+interface UpdateServerMetaOptions {
+    /** Server display name. */
+    name?: string;
+    /** Server description (set to `null` to clear). */
+    description?: string | null;
+    /** Tags for categorization. */
+    tags?: string[];
+    /** Operator name (set to `null` to clear). */
+    owner?: string | null;
+    /** Company name (set to `null` to clear). */
+    company?: string | null;
+    /** Contact email (set to `null` to clear). */
+    email?: string | null;
+}
+
+/**
+ * Client for the Zooid pub/sub API.
+ *
+ * Provides methods for channel management, event publishing/polling,
+ * webhook registration, and server metadata access.
+ *
+ * @example
+ * ```ts
+ * const client = new ZooidClient({
+ *   server: 'https://zooid.example.workers.dev',
+ *   token: 'eyJ...',
+ * });
+ *
+ * const channels = await client.listChannels();
+ * ```
+ */
+declare class ZooidClient {
+    /** Base URL of the Zooid server (trailing slashes stripped). */
+    readonly server: string;
+    private token?;
+    private _fetch;
+    constructor(options: ZooidClientOptions);
+    private request;
+    /** Fetch server discovery metadata from `GET /.well-known/zooid.json`. */
+    getMetadata(): Promise<ServerDiscovery>;
+    /** Fetch editable server identity from `GET /api/v1/server`. */
+    getServerMeta(): Promise<ServerIdentity>;
+    /** Update server identity metadata via `PUT /api/v1/server`. Requires admin token. */
+    updateServerMeta(options: UpdateServerMetaOptions): Promise<ServerIdentity>;
+    /** List all channels via `GET /api/v1/channels`. */
+    listChannels(): Promise<ChannelInfo[]>;
+    /** Create a new channel via `POST /api/v1/channels`. Requires admin token. */
+    createChannel(options: CreateChannelOptions): Promise<CreateChannelResult>;
+    /** Generate a signed claim for the Zooid Directory. Requires admin token. */
+    getClaim(channels: string[], action?: 'delete'): Promise<ClaimResult>;
+    /** Add a named publisher to a channel. Requires admin token. */
+    addPublisher(channelId: string, name: string): Promise<PublisherResult>;
+    /** Publish a single event to a channel. Requires a publish-scoped token. */
+    publish(channelId: string, options: PublishOptions): Promise<ZooidEvent$1>;
+    /** Publish multiple events in a single request. Requires a publish-scoped token. */
+    publishBatch(channelId: string, events: PublishOptions[]): Promise<ZooidEvent$1[]>;
+    /**
+     * Fetch events from a channel.
+     *
+     * Without `follow`, performs a one-shot poll (alias for {@link poll}).
+     * With `follow: true`, returns an async iterable stream that wraps {@link subscribe}.
+     *
+     * @example
+     * ```ts
+     * // One-shot
+     * const result = await client.tail('my-channel', { limit: 10 });
+     *
+     * // Follow mode
+     * const stream = client.tail('my-channel', { follow: true });
+     * for await (const event of stream) {
+     *   console.log(event);
+     * }
+     * ```
+     */
+    tail(channelId: string, options: TailOptions & {
+        follow: true;
+    }): TailStream;
+    tail(channelId: string, options?: TailOptions): Promise<PollResult>;
+    private createTailStream;
+    /** Poll events from a channel with cursor-based pagination. */
+    poll(channelId: string, options?: PollOptions): Promise<PollResult>;
+    /** Register a webhook to receive events via POST. */
+    registerWebhook(channelId: string, url: string, options?: WebhookOptions): Promise<WebhookResult>;
+    /** Remove a webhook registration. Requires admin token. */
+    removeWebhook(channelId: string, webhookId: string): Promise<void>;
+    /**
+     * Subscribe to a channel. Tries WebSocket first (mode `'auto'`), falls back to polling.
+     *
+     * Returns a promise that resolves with an unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const unsub = await client.subscribe('my-channel', (event) => {
+     *   console.log('New event:', event.id);
+     * });
+     *
+     * // Later: stop
+     * unsub();
+     * ```
+     */
+    subscribe(channelId: string, callback: (event: ZooidEvent$1) => void, options?: SubscribeOptions): Promise<() => void>;
+    private buildWsUrl;
+    private startPolling;
+}
+
+/**
+ * Error thrown by {@link ZooidClient} when the server returns a non-2xx response.
+ *
+ * The `status` property contains the HTTP status code, and `message` contains
+ * the error description from the response body (or a fallback like `"HTTP 500"`).
+ */
+declare class ZooidError extends Error {
+    /** HTTP status code from the server response. */
+    status: number;
+    constructor(status: number, message: string);
+}
+
+/** Options for verifying a Zooid webhook signature. */
+interface VerifyWebhookOptions {
+    /** The raw JSON request body string. */
+    body: string;
+    /** Base64-encoded Ed25519 signature from the `X-Zooid-Signature` header. */
+    signature: string;
+    /** ISO 8601 timestamp from the `X-Zooid-Timestamp` header. */
+    timestamp: string;
+    /** Base64-encoded SPKI public key from `/.well-known/zooid.json`. */
+    publicKey: string;
+    /** Maximum age in seconds before the timestamp is considered stale. Default: no check. */
+    maxAge?: number;
+}
+/**
+ * Verify an Ed25519 webhook signature from a Zooid server.
+ *
+ * @example
+ * ```ts
+ * import { verifyWebhook } from '@zooid/sdk';
+ *
+ * const isValid = await verifyWebhook({
+ *   body: rawBody,
+ *   signature: req.headers['x-zooid-signature'],
+ *   timestamp: req.headers['x-zooid-timestamp'],
+ *   publicKey: cachedPublicKey,
+ *   maxAge: 300,
+ * });
+ * ```
+ */
+declare function verifyWebhook(options: VerifyWebhookOptions): Promise<boolean>;
+
+export { type ChannelInfo, type ClaimResult, type CreateChannelOptions, type CreateChannelResult, type PollOptions, type PublishOptions, type PublisherResult, type SubscribeMode, type SubscribeOptions, type TailOptions, type TailStream, type UpdateServerMetaOptions, type VerifyWebhookOptions, type WebhookOptions, type WebhookResult, ZooidClient, type ZooidClientOptions, ZooidError, verifyWebhook };

package/dist/index.d.ts

@@ -0,0 +1,260 @@
+import { ChannelListItem, ZooidEvent as ZooidEvent$1, Webhook, ServerDiscovery, ServerIdentity, PollResult } from '@zooid/types';
+export { PollResult, ServerDiscovery, ServerIdentity, ServerMeta, ServerMetadata, ZooidEvent } from '@zooid/types';
+
+type ZooidEvent = ZooidEvent$1;
+/** Channel info as returned by `GET /api/v1/channels`. Alias for {@link ChannelListItem}. */
+type ChannelInfo = ChannelListItem;
+/** Webhook registration result. Alias for {@link Webhook}. */
+type WebhookResult = Webhook;
+/** Options for constructing a {@link ZooidClient}. */
+interface ZooidClientOptions {
+    /** Base URL of the Zooid server (e.g. `"https://zooid.example.workers.dev"`). */
+    server: string;
+    /** JWT token (admin, publish, or subscribe scoped). */
+    token?: string;
+    /** Custom fetch implementation (for testing or custom environments). */
+    fetch?: typeof globalThis.fetch;
+}
+/** Options for creating a new channel via `POST /api/v1/channels`. */
+interface CreateChannelOptions {
+    /** URL-safe slug identifier (lowercase + hyphens, 3-64 chars). */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Optional channel description. */
+    description?: string;
+    /** Whether the channel is publicly accessible. Defaults to `true`. */
+    is_public?: boolean;
+    /** Optional JSON Schema for event payload validation. */
+    schema?: Record<string, unknown>;
+    /** When `true`, events are rejected if they don't match `schema`. */
+    strict?: boolean;
+}
+/** Result of creating a new channel. */
+interface CreateChannelResult {
+    /** The channel's slug identifier. */
+    id: string;
+    /** JWT token scoped for publishing to this channel. */
+    publish_token: string;
+    /** JWT token scoped for subscribing to this channel. */
+    subscribe_token: string;
+}
+/** Result of adding a publisher to a channel. */
+interface PublisherResult {
+    /** ULID identifier for the new publisher. */
+    id: string;
+    /** Display name of the publisher. */
+    name: string;
+    /** JWT token scoped for publishing as this publisher. */
+    publish_token: string;
+}
+/** Options for publishing a single event. */
+interface PublishOptions {
+    /** Optional event type string for subscriber filtering. */
+    type?: string;
+    /** Event payload (will be JSON-serialized, max 64 KB). */
+    data: unknown;
+}
+/** Options for polling events from a channel. */
+interface PollOptions {
+    /** Opaque cursor from a previous poll response. */
+    cursor?: string;
+    /** ISO 8601 timestamp — only return events created after this time. */
+    since?: string;
+    /** Maximum number of events to return (default: 50). */
+    limit?: number;
+    /** Filter events by type. */
+    type?: string;
+}
+/** Options for registering a webhook. */
+interface WebhookOptions {
+    /** Only deliver events matching these types. Omit for all events. */
+    event_types?: string[];
+    /** Webhook lifetime in seconds (default: 3 days, max: 30 days). */
+    ttl_seconds?: number;
+}
+/** Subscribe transport mode. */
+type SubscribeMode = 'auto' | 'ws' | 'poll';
+/** Options for the subscribe helper. */
+interface SubscribeOptions {
+    /** Polling interval in milliseconds. Default: `5000`. */
+    interval?: number;
+    /** Transport mode. `'auto'` (default) tries WebSocket first, falls back to polling. */
+    mode?: SubscribeMode;
+    /** Event type filter — passed as `?types=` on WS, `?type=` on poll. */
+    type?: string;
+}
+/** Options for the `tail()` method. Extends poll options with follow mode. */
+interface TailOptions extends PollOptions {
+    /** When `true`, subscribe and stream events as they arrive. */
+    follow?: boolean;
+    /** Transport mode for follow mode. Default: `'auto'`. */
+    mode?: SubscribeMode;
+    /** Polling interval in ms for follow mode (poll transport). Default: `5000`. */
+    interval?: number;
+}
+/**
+ * An async iterable stream of events returned by `tail({ follow: true })`.
+ * Call `close()` to stop the underlying subscription and end the stream.
+ */
+interface TailStream extends AsyncIterable<ZooidEvent> {
+    /** Stop the subscription and end the stream. */
+    close(): void;
+}
+/** Result of generating a signed directory claim. */
+interface ClaimResult {
+    /** Base64url-encoded JSON claim payload. */
+    claim: string;
+    /** Base64url-encoded Ed25519 signature of the claim. */
+    signature: string;
+}
+/** Options for updating server identity metadata. */
+interface UpdateServerMetaOptions {
+    /** Server display name. */
+    name?: string;
+    /** Server description (set to `null` to clear). */
+    description?: string | null;
+    /** Tags for categorization. */
+    tags?: string[];
+    /** Operator name (set to `null` to clear). */
+    owner?: string | null;
+    /** Company name (set to `null` to clear). */
+    company?: string | null;
+    /** Contact email (set to `null` to clear). */
+    email?: string | null;
+}
+
+/**
+ * Client for the Zooid pub/sub API.
+ *
+ * Provides methods for channel management, event publishing/polling,
+ * webhook registration, and server metadata access.
+ *
+ * @example
+ * ```ts
+ * const client = new ZooidClient({
+ *   server: 'https://zooid.example.workers.dev',
+ *   token: 'eyJ...',
+ * });
+ *
+ * const channels = await client.listChannels();
+ * ```
+ */
+declare class ZooidClient {
+    /** Base URL of the Zooid server (trailing slashes stripped). */
+    readonly server: string;
+    private token?;
+    private _fetch;
+    constructor(options: ZooidClientOptions);
+    private request;
+    /** Fetch server discovery metadata from `GET /.well-known/zooid.json`. */
+    getMetadata(): Promise<ServerDiscovery>;
+    /** Fetch editable server identity from `GET /api/v1/server`. */
+    getServerMeta(): Promise<ServerIdentity>;
+    /** Update server identity metadata via `PUT /api/v1/server`. Requires admin token. */
+    updateServerMeta(options: UpdateServerMetaOptions): Promise<ServerIdentity>;
+    /** List all channels via `GET /api/v1/channels`. */
+    listChannels(): Promise<ChannelInfo[]>;
+    /** Create a new channel via `POST /api/v1/channels`. Requires admin token. */
+    createChannel(options: CreateChannelOptions): Promise<CreateChannelResult>;
+    /** Generate a signed claim for the Zooid Directory. Requires admin token. */
+    getClaim(channels: string[], action?: 'delete'): Promise<ClaimResult>;
+    /** Add a named publisher to a channel. Requires admin token. */
+    addPublisher(channelId: string, name: string): Promise<PublisherResult>;
+    /** Publish a single event to a channel. Requires a publish-scoped token. */
+    publish(channelId: string, options: PublishOptions): Promise<ZooidEvent$1>;
+    /** Publish multiple events in a single request. Requires a publish-scoped token. */
+    publishBatch(channelId: string, events: PublishOptions[]): Promise<ZooidEvent$1[]>;
+    /**
+     * Fetch events from a channel.
+     *
+     * Without `follow`, performs a one-shot poll (alias for {@link poll}).
+     * With `follow: true`, returns an async iterable stream that wraps {@link subscribe}.
+     *
+     * @example
+     * ```ts
+     * // One-shot
+     * const result = await client.tail('my-channel', { limit: 10 });
+     *
+     * // Follow mode
+     * const stream = client.tail('my-channel', { follow: true });
+     * for await (const event of stream) {
+     *   console.log(event);
+     * }
+     * ```
+     */
+    tail(channelId: string, options: TailOptions & {
+        follow: true;
+    }): TailStream;
+    tail(channelId: string, options?: TailOptions): Promise<PollResult>;
+    private createTailStream;
+    /** Poll events from a channel with cursor-based pagination. */
+    poll(channelId: string, options?: PollOptions): Promise<PollResult>;
+    /** Register a webhook to receive events via POST. */
+    registerWebhook(channelId: string, url: string, options?: WebhookOptions): Promise<WebhookResult>;
+    /** Remove a webhook registration. Requires admin token. */
+    removeWebhook(channelId: string, webhookId: string): Promise<void>;
+    /**
+     * Subscribe to a channel. Tries WebSocket first (mode `'auto'`), falls back to polling.
+     *
+     * Returns a promise that resolves with an unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const unsub = await client.subscribe('my-channel', (event) => {
+     *   console.log('New event:', event.id);
+     * });
+     *
+     * // Later: stop
+     * unsub();
+     * ```
+     */
+    subscribe(channelId: string, callback: (event: ZooidEvent$1) => void, options?: SubscribeOptions): Promise<() => void>;
+    private buildWsUrl;
+    private startPolling;
+}
+
+/**
+ * Error thrown by {@link ZooidClient} when the server returns a non-2xx response.
+ *
+ * The `status` property contains the HTTP status code, and `message` contains
+ * the error description from the response body (or a fallback like `"HTTP 500"`).
+ */
+declare class ZooidError extends Error {
+    /** HTTP status code from the server response. */
+    status: number;
+    constructor(status: number, message: string);
+}
+
+/** Options for verifying a Zooid webhook signature. */
+interface VerifyWebhookOptions {
+    /** The raw JSON request body string. */
+    body: string;
+    /** Base64-encoded Ed25519 signature from the `X-Zooid-Signature` header. */
+    signature: string;
+    /** ISO 8601 timestamp from the `X-Zooid-Timestamp` header. */
+    timestamp: string;
+    /** Base64-encoded SPKI public key from `/.well-known/zooid.json`. */
+    publicKey: string;
+    /** Maximum age in seconds before the timestamp is considered stale. Default: no check. */
+    maxAge?: number;
+}
+/**
+ * Verify an Ed25519 webhook signature from a Zooid server.
+ *
+ * @example
+ * ```ts
+ * import { verifyWebhook } from '@zooid/sdk';
+ *
+ * const isValid = await verifyWebhook({
+ *   body: rawBody,
+ *   signature: req.headers['x-zooid-signature'],
+ *   timestamp: req.headers['x-zooid-timestamp'],
+ *   publicKey: cachedPublicKey,
+ *   maxAge: 300,
+ * });
+ * ```
+ */
+declare function verifyWebhook(options: VerifyWebhookOptions): Promise<boolean>;
+
+export { type ChannelInfo, type ClaimResult, type CreateChannelOptions, type CreateChannelResult, type PollOptions, type PublishOptions, type PublisherResult, type SubscribeMode, type SubscribeOptions, type TailOptions, type TailStream, type UpdateServerMetaOptions, type VerifyWebhookOptions, type WebhookOptions, type WebhookResult, ZooidClient, type ZooidClientOptions, ZooidError, verifyWebhook };

package/dist/index.js

@@ -0,0 +1,322 @@
+// src/error.ts
+var ZooidError = class extends Error {
+  /** HTTP status code from the server response. */
+  status;
+  constructor(status, message) {
+    super(message);
+    this.name = "ZooidError";
+    this.status = status;
+  }
+};
+
+// src/client.ts
+var ZooidClient = class {
+  /** Base URL of the Zooid server (trailing slashes stripped). */
+  server;
+  token;
+  _fetch;
+  constructor(options) {
+    this.server = options.server.replace(/\/+$/, "");
+    this.token = options.token;
+    this._fetch = options.fetch ?? globalThis.fetch;
+  }
+  async request(method, path, body) {
+    const headers = {};
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    const res = await this._fetch(this.server + path, {
+      method,
+      headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      let message = `HTTP ${res.status}`;
+      try {
+        const json = await res.json();
+        if (json.error) message = String(json.error);
+      } catch {
+      }
+      throw new ZooidError(res.status, message);
+    }
+    if (res.status === 204) {
+      return void 0;
+    }
+    return res.json();
+  }
+  /** Fetch server discovery metadata from `GET /.well-known/zooid.json`. */
+  async getMetadata() {
+    return this.request("GET", "/.well-known/zooid.json");
+  }
+  /** Fetch editable server identity from `GET /api/v1/server`. */
+  async getServerMeta() {
+    return this.request("GET", "/api/v1/server");
+  }
+  /** Update server identity metadata via `PUT /api/v1/server`. Requires admin token. */
+  async updateServerMeta(options) {
+    return this.request("PUT", "/api/v1/server", options);
+  }
+  /** List all channels via `GET /api/v1/channels`. */
+  async listChannels() {
+    const res = await this.request("GET", "/api/v1/channels");
+    return res.channels;
+  }
+  /** Create a new channel via `POST /api/v1/channels`. Requires admin token. */
+  async createChannel(options) {
+    return this.request("POST", "/api/v1/channels", options);
+  }
+  /** Generate a signed claim for the Zooid Directory. Requires admin token. */
+  async getClaim(channels, action) {
+    const body = { channels };
+    if (action) body.action = action;
+    return this.request("POST", "/api/v1/directory/claim", body);
+  }
+  /** Add a named publisher to a channel. Requires admin token. */
+  async addPublisher(channelId, name) {
+    return this.request(
+      "POST",
+      `/api/v1/channels/${channelId}/publishers`,
+      { name }
+    );
+  }
+  /** Publish a single event to a channel. Requires a publish-scoped token. */
+  async publish(channelId, options) {
+    const body = { data: options.data };
+    if (options.type !== void 0) {
+      body.type = options.type;
+    }
+    return this.request("POST", `/api/v1/channels/${channelId}/events`, body);
+  }
+  /** Publish multiple events in a single request. Requires a publish-scoped token. */
+  async publishBatch(channelId, events) {
+    const body = {
+      events: events.map((e) => {
+        const item = { data: e.data };
+        if (e.type !== void 0) item.type = e.type;
+        return item;
+      })
+    };
+    const res = await this.request(
+      "POST",
+      `/api/v1/channels/${channelId}/events`,
+      body
+    );
+    return res.events;
+  }
+  tail(channelId, options) {
+    if (options?.follow) {
+      return this.createTailStream(channelId, options);
+    }
+    return this.poll(channelId, options);
+  }
+  createTailStream(channelId, options) {
+    const buffer = [];
+    let waiting = null;
+    let done = false;
+    let unsub = null;
+    this.subscribe(channelId, (event) => {
+      if (waiting) {
+        const resolve = waiting;
+        waiting = null;
+        resolve({ value: event, done: false });
+      } else {
+        buffer.push(event);
+      }
+    }, {
+      mode: options.mode,
+      interval: options.interval,
+      type: options.type
+    }).then((fn) => {
+      unsub = fn;
+      if (done) fn();
+    });
+    const stream = {
+      close() {
+        done = true;
+        unsub?.();
+        if (waiting) {
+          waiting({ value: void 0, done: true });
+          waiting = null;
+        }
+      },
+      [Symbol.asyncIterator]() {
+        return {
+          next() {
+            if (buffer.length > 0) {
+              return Promise.resolve({ value: buffer.shift(), done: false });
+            }
+            if (done) {
+              return Promise.resolve({ value: void 0, done: true });
+            }
+            return new Promise((resolve) => {
+              waiting = resolve;
+            });
+          },
+          return() {
+            stream.close();
+            return Promise.resolve({ value: void 0, done: true });
+          }
+        };
+      }
+    };
+    return stream;
+  }
+  /** Poll events from a channel with cursor-based pagination. */
+  async poll(channelId, options) {
+    const params = new URLSearchParams();
+    if (options?.cursor) params.set("cursor", options.cursor);
+    if (options?.limit !== void 0) params.set("limit", String(options.limit));
+    if (options?.type) params.set("type", options.type);
+    if (options?.since) params.set("since", options.since);
+    const qs = params.toString();
+    const path = `/api/v1/channels/${channelId}/events${qs ? `?${qs}` : ""}`;
+    return this.request("GET", path);
+  }
+  /** Register a webhook to receive events via POST. */
+  async registerWebhook(channelId, url, options) {
+    return this.request("POST", `/api/v1/channels/${channelId}/webhooks`, {
+      url,
+      ...options
+    });
+  }
+  /** Remove a webhook registration. Requires admin token. */
+  async removeWebhook(channelId, webhookId) {
+    await this.request(
+      "DELETE",
+      `/api/v1/channels/${channelId}/webhooks/${webhookId}`
+    );
+  }
+  /**
+   * Subscribe to a channel. Tries WebSocket first (mode `'auto'`), falls back to polling.
+   *
+   * Returns a promise that resolves with an unsubscribe function.
+   *
+   * @example
+   * ```ts
+   * const unsub = await client.subscribe('my-channel', (event) => {
+   *   console.log('New event:', event.id);
+   * });
+   *
+   * // Later: stop
+   * unsub();
+   * ```
+   */
+  async subscribe(channelId, callback, options) {
+    const mode = options?.mode ?? "auto";
+    if (mode === "poll") {
+      return this.startPolling(channelId, callback, options);
+    }
+    const tryWs = (retryOnFail) => {
+      return new Promise((resolve, reject) => {
+        const url = this.buildWsUrl(channelId, options);
+        const ws = new globalThis.WebSocket(url);
+        ws.onopen = () => {
+          resolve(() => {
+            ws.close();
+          });
+        };
+        ws.onmessage = (e) => {
+          try {
+            const event = JSON.parse(String(e.data));
+            callback(event);
+          } catch {
+          }
+        };
+        ws.onclose = () => {
+        };
+        ws.onerror = () => {
+          ws.close();
+          if (retryOnFail) {
+            setTimeout(() => {
+              tryWs(false).then(resolve, reject);
+            }, 1e3);
+          } else if (mode === "auto") {
+            this.startPolling(channelId, callback, options).then(resolve, reject);
+          } else {
+            reject(new Error("WebSocket connection failed"));
+          }
+        };
+      });
+    };
+    return tryWs(true);
+  }
+  buildWsUrl(channelId, options) {
+    const base = this.server.replace(/^http:\/\//, "ws://").replace(/^https:\/\//, "wss://");
+    const params = new URLSearchParams();
+    if (this.token) params.set("token", this.token);
+    if (options?.type) params.set("types", options.type);
+    const qs = params.toString();
+    return `${base}/api/v1/channels/${channelId}/ws${qs ? `?${qs}` : ""}`;
+  }
+  startPolling(channelId, callback, options) {
+    const interval = options?.interval ?? 5e3;
+    const type = options?.type;
+    let cursor = null;
+    let timer = null;
+    let stopped = false;
+    const doPoll = async () => {
+      try {
+        const pollOpts = {};
+        if (cursor) pollOpts.cursor = cursor;
+        if (type) pollOpts.type = type;
+        const result = await this.poll(channelId, pollOpts);
+        if (stopped) return;
+        for (const event of result.events) {
+          callback(event);
+        }
+        if (result.cursor) {
+          cursor = result.cursor;
+        }
+      } catch {
+      }
+    };
+    doPoll();
+    timer = setInterval(doPoll, interval);
+    return Promise.resolve(() => {
+      stopped = true;
+      if (timer !== null) {
+        clearInterval(timer);
+        timer = null;
+      }
+    });
+  }
+};
+
+// src/verify.ts
+async function verifyWebhook(options) {
+  const { body, signature, timestamp, publicKey, maxAge } = options;
+  if (maxAge !== void 0) {
+    const ts = Date.parse(timestamp);
+    if (Number.isNaN(ts)) return false;
+    const age = (Date.now() - ts) / 1e3;
+    if (age > maxAge || age < -maxAge) return false;
+  }
+  const key = await crypto.subtle.importKey(
+    "spki",
+    base64ToArrayBuffer(publicKey),
+    "Ed25519",
+    false,
+    ["verify"]
+  );
+  const message = new TextEncoder().encode(`${timestamp}.${body}`);
+  const sigBytes = base64ToArrayBuffer(signature);
+  return crypto.subtle.verify("Ed25519", key, sigBytes, message);
+}
+function base64ToArrayBuffer(input) {
+  const base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+export {
+  ZooidClient,
+  ZooidError,
+  verifyWebhook
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@zooid/sdk",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "@zooid/types": "0.0.1"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.8.34",
+    "tsup": "^8.5.1",
+    "vitest": "^3.2.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "author": "Ori Ben",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zooid-ai/zooid",
+    "directory": "packages/sdk"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts"
+  }
+}