@dotwire/host 0.0.0-stage → 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,464 @@
+type DotwireRole = 'member' | 'auditor' | 'admin';
+interface DotwireHostConfig {
+    baseUrl: string;
+    issuer: string;
+    audience?: string;
+    keyId: string;
+    privateKeyPem: string;
+    adminUserId?: string;
+    auditorUserId?: string;
+    /** jose-style duration string (e.g. "15m"), passed straight through to `SignJWT#setExpirationTime`. */
+    defaultTokenTtl?: string;
+    requestTimeoutMs?: number;
+    /** HMAC-SHA256 secret used to verify `X-Dotwire-Signature` on incoming webhook calls. */
+    webhookSecret?: string;
+    roleCacheTtlMs?: number;
+    /** Every request goes through this so tests can inject a fake. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /**
+     * Runs in-process before {@link DotwireHostClient.sendAsUser} and {@link DotwireHostClient.handleClientSend},
+     * and inside {@link DotwireHostClient.handlePresendWebhook} - one place for moderation logic that
+     * covers both host-initiated sends and messages sent directly by `@dotwire/client`.
+     */
+    presend?: (ctx: PresendContext) => Promise<PresendResult> | PresendResult;
+    /** Same idea as {@link presend}, run after a message is accepted; see {@link PostSendContext}. */
+    postSend?: (ctx: PostSendContext) => Promise<void> | void;
+}
+interface MintTokenOptions {
+    role?: DotwireRole;
+    displayName?: string;
+    /** jose-style duration string, e.g. "15m". Defaults to `config.defaultTokenTtl`. */
+    ttl?: string;
+}
+interface PresendContext {
+    roomId: string;
+    content: string;
+    senderUserId: string;
+}
+interface PresendResult {
+    allow: boolean;
+    /** Rewritten content; only meaningful when `allow` is true. */
+    content?: string;
+    rejectionReason?: string;
+}
+declare const PresendResult: {
+    accept(content?: string): PresendResult;
+    reject(reason: string): PresendResult;
+};
+/** What a postSend hook sees: the accepted message plus its ack, so it can be found again by (roomId, seq). */
+interface PostSendContext {
+    roomId: string;
+    seq: number;
+    time: string;
+    content: string;
+    senderUserId: string;
+}
+interface SendMessageResult {
+    seq: number;
+    time: string;
+}
+interface HistoryMessage {
+    seq: number;
+    time: string;
+    senderId: string;
+    content: string;
+}
+interface RoomHistoryResponse {
+    roomId: string;
+    messages: HistoryMessage[];
+    hasMore: boolean;
+}
+interface UserRoleResponse {
+    userId: string;
+    role: DotwireRole;
+}
+interface RoomMembersResponse {
+    roomId: string;
+    members: string[];
+}
+interface UserRoomsResponse {
+    userId: string;
+    roomIds: string[];
+}
+interface RedactMessageResponse {
+    roomId: string;
+    seq: number;
+    removedFromHistory: boolean;
+    removedFromStream: boolean;
+}
+interface RetentionResponse {
+    messagesDays: number;
+}
+interface AuditEntry {
+    id: number;
+    eventType: string;
+    roomId: string | null;
+    messageSeq: number | null;
+    actorId: string | null;
+    subjectId: string | null;
+    value: number | null;
+    time: string;
+    hash: string;
+}
+interface AuditPageResponse {
+    events: AuditEntry[];
+    hasMore: boolean;
+}
+interface AuditVerificationResponse {
+    ok: boolean;
+    fromId: number;
+    toId: number;
+    checked: number;
+    firstInvalidId: number | null;
+    anchor: string | null;
+}
+interface AuditCheckpointEntry {
+    day: string;
+    lastId: number;
+    hash: string;
+    createdAt: string;
+}
+interface AuditCheckpointsResponse {
+    checkpoints: AuditCheckpointEntry[];
+}
+interface UserExportMessage {
+    roomId: string;
+    seq: number;
+    time: string;
+    content: string | null;
+    undecryptable?: boolean;
+}
+interface UserExportAuditEvent {
+    id: number;
+    eventType: string;
+    roomId: string | null;
+    messageSeq: number | null;
+    actorId: string | null;
+    subjectId: string | null;
+    value: number | null;
+    time: string;
+}
+interface UserExport {
+    userId: string;
+    exportedAt: string;
+    role: DotwireRole | null;
+    roomIds: string[];
+    messages: UserExportMessage[];
+    auditEvents: UserExportAuditEvent[];
+}
+interface GetMessagesOptions {
+    asUserId: string;
+    afterSeq?: number;
+    beforeSeq?: number;
+    limit?: number;
+}
+interface AddRoomMembersOptions {
+    /** Grants `member` to any listed user with no existing role, without touching an existing auditor/admin. Default true. */
+    ensureMemberRole?: boolean;
+}
+interface SendSystemMessageOptions {
+    /** Defaults to "system". */
+    senderId?: string;
+}
+interface StreamRoomEventsOptions {
+    asUserId: string;
+    afterSeq?: number;
+    /** Reconnect on drop with `Last-Event-ID`, exponential backoff 1s..30s, until cancelled or revoked. Default true. */
+    autoResume?: boolean;
+    signal?: AbortSignal;
+}
+interface TokenResponseOptions {
+    userId: string;
+    role?: DotwireRole;
+    displayName?: string;
+    ttl?: string;
+}
+/** Discriminated union of everything `GET /rooms/{roomId}/events` can emit (spec §3.9). */
+type RoomEvent = {
+    type: 'message';
+    roomId: string;
+    seq: number;
+    senderId: string;
+    time: string;
+    content: string;
+    replayed?: boolean;
+} | {
+    type: 'retracted';
+    roomId: string;
+    seq: number;
+} | {
+    type: 'typing';
+    roomId: string;
+    userId: string;
+    isTyping: boolean;
+} | {
+    type: 'presence';
+    roomId: string;
+    joined: string[];
+    left: string[];
+} | {
+    type: 'revoked';
+    roomId: string;
+};
+/** Result of {@link DotwireHostClient.handleClientSendBody} / the Request-based `handleClientSend`. */
+interface ClientSendResult {
+    status: number;
+    body: {
+        seq: number;
+        time: string;
+    } | {
+        error: string;
+        reason?: string;
+    };
+}
+/** Result of the two webhook handlers' body-based variants. */
+interface WebhookResult {
+    status: number;
+    body: {
+        allow: boolean;
+        content?: string;
+        reason?: string;
+    } | Record<string, never>;
+}
+
+/**
+ * Mirrors `Dotwire.Host.DotwireApiException.Kind` (.NET) / the wire error contract in spec §3.14.
+ * Mapped from HTTP status first, then the `error` code in the body.
+ */
+type DotwireApiErrorKind = 'BadRequest' | 'Unauthorized' | 'Forbidden' | 'NotFound' | 'PresendRejected' | 'RateLimited' | 'Unavailable' | 'Unknown';
+interface DotwireApiErrorInit {
+    status: number;
+    kind: DotwireApiErrorKind;
+    code?: string;
+    reason?: string;
+    retryAfterMs?: number;
+    method: string;
+    path: string;
+}
+/** Thrown when the dotwire server answers a request with a non-success status. */
+declare class DotwireApiError extends Error {
+    readonly status: number;
+    readonly kind: DotwireApiErrorKind;
+    readonly code?: string;
+    readonly reason?: string;
+    readonly retryAfterMs?: number;
+    readonly method: string;
+    readonly path: string;
+    constructor(init: DotwireApiErrorInit);
+}
+/**
+ * Maps an HTTP status (and, where ambiguous, the wire error code from spec §3.14) to a
+ * {@link DotwireApiErrorKind}. Status is authoritative; code only disambiguates 422/503/429/400.
+ */
+declare function mapErrorKind(status: number, code?: string): DotwireApiErrorKind;
+/**
+ * Thrown when the host's own {@link DotwireHostConfig.presend} hook rejects a message, evaluated
+ * in-process before the message ever reaches the wire (no network round-trip). Distinct from a
+ * {@link DotwireApiError} with kind `PresendRejected`, which is the *server's* configured presend
+ * webhook rejecting a message on `POST /rooms/{roomId}/messages` (a different, server-side hook).
+ */
+declare class PresendRejectedError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * The message WAS sent (see {@link sent}); only the local `postSend` hook failed afterwards.
+ * Kept distinct from a send failure so callers never retry a send that already succeeded.
+ */
+declare class PostSendError extends Error {
+    readonly sent: SendMessageResult;
+    constructor(sent: SendMessageResult, cause: unknown);
+}
+
+declare class DotwireTokenSigner {
+    private readonly config;
+    private readonly keyPromise;
+    private readonly defaultTtl;
+    constructor(config: DotwireHostConfig);
+    mintToken(userId: string, options?: MintTokenOptions): Promise<string>;
+}
+
+/**
+ * Node/TypeScript counterpart of `Dotwire.Host.DotwireHostClient` (.NET). Mints its own tokens
+ * and talks to a dotwire server entirely over its frozen HTTP surface - see spec §3 for the
+ * server's wire shapes and §4/§5 for the identity and role-resolution rules this class follows.
+ */
+declare class DotwireHostClient {
+    private readonly config;
+    private readonly signer;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly requestTimeoutMs;
+    private readonly adminUserId;
+    private readonly auditorUserId;
+    private readonly defaultTtl;
+    private readonly roleCache;
+    private readonly adminToken;
+    private readonly auditorToken;
+    presend?: (ctx: PresendContext) => Promise<PresendResult> | PresendResult;
+    postSend?: (ctx: PostSendContext) => Promise<void> | void;
+    constructor(config: DotwireHostConfig);
+    /** Mints a token directly. An explicit `role` bypasses all role resolution. */
+    mintToken(userId: string, options?: MintTokenOptions): Promise<string>;
+    /**
+     * Returns a `Response` with body `{ token }`. When `role` is omitted, resolves it through the
+     * cached admin lookup and falls back to `member` for an unknown user (404 on the lookup) since
+     * there is no request of its own to fail here.
+     */
+    tokenResponse(options: TokenResponseOptions): Promise<Response>;
+    private resolveRoleForToken;
+    setUserRole(userId: string, role: DotwireRole): Promise<UserRoleResponse>;
+    getUserRole(userId: string): Promise<UserRoleResponse | null>;
+    deleteUserRole(userId: string): Promise<void>;
+    getUserRooms(userId: string): Promise<string[]>;
+    exportUser(userId: string): Promise<UserExport>;
+    /** Returns the raw response stream so the caller can pipe an arbitrarily large export without buffering it. */
+    exportUserStream(userId: string): Promise<ReadableStream<Uint8Array>>;
+    private lookupRole;
+    room(roomId: string): DotwireHostRoom;
+    addRoomMembers(roomId: string, userIds: string[], options?: AddRoomMembersOptions): Promise<string[]>;
+    removeRoomMember(roomId: string, userId: string): Promise<void>;
+    getRoomMembers(roomId: string): Promise<string[]>;
+    /** Reads participants under the user's own room membership, without admin access. */
+    getRoomParticipants(roomId: string, asUserId: string): Promise<string[]>;
+    sendAsUser(roomId: string, userId: string, content: string): Promise<SendMessageResult>;
+    /** Admin message injection (spec §3.3). Presend/postSend hooks do not run for system injections. */
+    sendSystemMessage(roomId: string, content: string, options?: SendSystemMessageOptions): Promise<SendMessageResult>;
+    getMessages(roomId: string, options: GetMessagesOptions): Promise<RoomHistoryResponse>;
+    /** Parses SSE from `GET /rooms/{roomId}/events`, reconnecting on drop when `autoResume` (default true). */
+    streamRoomEvents(roomId: string, options: StreamRoomEventsOptions): AsyncIterable<RoomEvent>;
+    private streamRoomEventsGenerator;
+    redactMessage(roomId: string, seq: number): Promise<RedactMessageResponse>;
+    readAuditLog(afterId?: number, limit?: number): Promise<AuditPageResponse>;
+    verifyAuditLog(full?: boolean): Promise<AuditVerificationResponse>;
+    getAuditCheckpoints(limit?: number): Promise<AuditCheckpointsResponse['checkpoints']>;
+    getMessageRetentionDays(): Promise<number>;
+    setMessageRetentionDays(days: number): Promise<number>;
+    /** Parses `{ roomId, content }`, calls {@link sendAsUser}, and mirrors the server's own send response shape/status. */
+    handleClientSend(request: Request, senderUserId: string): Promise<Response>;
+    /** Express-friendly variant: `body` is already-parsed JSON. */
+    handleClientSendBody(body: unknown, senderUserId: string): Promise<ClientSendResult>;
+    private handleClientSendCore;
+    /** Verifies `X-Dotwire-Signature` (when `webhookSecret` is set), runs the local `presend` hook, and mirrors the server's presend webhook response shape. */
+    handlePresendWebhook(request: Request): Promise<Response>;
+    handlePresendWebhookBody(body: unknown, signatureHeader?: string | null, rawBody?: string): Promise<WebhookResult>;
+    private handlePresendWebhookCore;
+    /** Verifies the signature, runs the local `postSend` hook, and always answers `{}` (postsend is best-effort). */
+    handlePostSendWebhook(request: Request): Promise<Response>;
+    handlePostSendWebhookBody(body: unknown, signatureHeader?: string | null, rawBody?: string): Promise<WebhookResult>;
+    private handlePostSendWebhookCore;
+    private verifySignature;
+    private adminRequest;
+    private auditorRequest;
+    /**
+     * Role resolution for user-scoped operations (spec §4.3 / §5): try the cached role (or
+     * `member` when nothing is cached); on 403, look the role up through the admin API, cache it,
+     * and retry once. A second 403 surfaces as a `Forbidden` {@link DotwireApiError}.
+     */
+    private fetchAsUser;
+    private rawFetch;
+    private throwIfError;
+}
+
+/** Mirrors {@link DotwireHostClient}'s room-scoped methods without the repeated `roomId` argument. */
+declare class DotwireHostRoom {
+    private readonly client;
+    readonly roomId: string;
+    constructor(client: DotwireHostClient, roomId: string);
+    addMembers(userIds: string[], options?: AddRoomMembersOptions): Promise<string[]>;
+    removeMember(userId: string): Promise<void>;
+    getMembers(): Promise<string[]>;
+    getParticipants(asUserId: string): Promise<string[]>;
+    sendAsUser(userId: string, content: string): Promise<SendMessageResult>;
+    sendSystemMessage(content: string, options?: SendSystemMessageOptions): Promise<SendMessageResult>;
+    getMessages(options: GetMessagesOptions): Promise<RoomHistoryResponse>;
+    events(options: StreamRoomEventsOptions): AsyncIterable<RoomEvent>;
+    redact(seq: number): Promise<RedactMessageResponse>;
+}
+
+/** An accepted message awaiting asynchronous review. (roomId, seq) is the redaction target. */
+interface PendingModeration {
+    roomId: string;
+    seq: number;
+    time: string;
+    senderUserId: string;
+    content: string;
+}
+/** One classifier decision. Only flagged verdicts trigger an action. */
+interface ModerationVerdict {
+    roomId: string;
+    seq: number;
+    flagged: boolean;
+    category?: string;
+    reason?: string;
+}
+/**
+ * The expensive judgment call, run off the send path over a whole batch at once. Implementations
+ * call an LLM (see `samples/moderation` for a Claude Message Batches API reference implementation),
+ * a third-party moderation API, or anything else too slow to sit inside a send. Return one verdict
+ * per input; inputs with no verdict are treated as not flagged.
+ */
+interface ModerationClassifier {
+    classify(batch: readonly PendingModeration[], signal?: AbortSignal): Promise<readonly ModerationVerdict[]>;
+}
+/**
+ * In-process hand-off between the send path and the {@link BatchModerationWorker}. Enqueueing
+ * (via {@link postSendHook}) is a microtask-cheap array push, so wiring it into
+ * `DotwireHostConfig.postSend` adds no meaningful latency to a send. The verdict itself is
+ * computed later, in batches, by the worker.
+ *
+ * Bounded at `capacity`: once full, {@link enqueue} (and therefore `postSendHook`) waits for
+ * room rather than silently dropping - the queue applies back-pressure to sends, mirroring the
+ * .NET port's `BoundedChannelFullMode.Wait` default.
+ */
+declare class ModerationQueue {
+    private readonly items;
+    private readonly waitingReaders;
+    private readonly waitingWriters;
+    private completed;
+    private readonly capacity;
+    constructor(capacity?: number);
+    enqueue(item: PendingModeration, signal?: AbortSignal): Promise<void>;
+    /** Assign directly: `client.postSend = queue.postSendHook`. */
+    postSendHook: (ctx: PostSendContext) => Promise<void>;
+    /** Signals the worker to drain what is queued and stop. */
+    complete(): void;
+    /** Blocks for an item; resolves null once completed and drained, or if `signal` fires. */
+    dequeue(signal?: AbortSignal): Promise<PendingModeration | null>;
+    /** Waits up to `timeoutMs` for an item. Resolves 'timeout' on expiry, null on completion/abort. */
+    tryDequeue(timeoutMs: number, signal?: AbortSignal): Promise<PendingModeration | null | 'timeout'>;
+    private take;
+    private waitForWriteSlot;
+    private wake;
+}
+interface BatchModerationOptions {
+    /** Flush when this many messages are queued... Default 100. */
+    maxBatchSize?: number;
+    /** ...or when the oldest queued message has waited this long, whichever comes first. Default 30000. */
+    maxBatchDelayMs?: number;
+    /** Classifier attempts per batch (exponential backoff between them) before the batch is dropped. Default 3. */
+    maxClassifierAttempts?: number;
+}
+/**
+ * Drains a {@link ModerationQueue} in size-or-time bounded batches, hands each batch to the
+ * {@link ModerationClassifier}, and runs `onFlagged` for every flagged verdict (typically
+ * {@link BatchModerationWorker.redactWith}). Runs entirely off the send path.
+ */
+declare class BatchModerationWorker {
+    private readonly queue;
+    private readonly classifier;
+    private readonly onFlagged;
+    private readonly onError?;
+    private readonly maxBatchSize;
+    private readonly maxBatchDelayMs;
+    private readonly maxClassifierAttempts;
+    constructor(queue: ModerationQueue, classifier: ModerationClassifier, onFlagged: (verdict: ModerationVerdict, signal?: AbortSignal) => Promise<void> | void, options?: BatchModerationOptions, onError?: (err: unknown) => void);
+    /** The usual action: physically redact the flagged message through the admin API, honouring `Retry-After` on 429. */
+    static redactWith(host: DotwireHostClient): (verdict: ModerationVerdict) => Promise<void>;
+    /** Runs until `signal` fires or the queue is completed and drained. */
+    run(signal: AbortSignal): Promise<void>;
+    private fillBatch;
+    private processBatch;
+}
+
+export { type AddRoomMembersOptions, type AuditCheckpointEntry, type AuditCheckpointsResponse, type AuditEntry, type AuditPageResponse, type AuditVerificationResponse, type BatchModerationOptions, BatchModerationWorker, type ClientSendResult, DotwireApiError, type DotwireApiErrorInit, type DotwireApiErrorKind, DotwireHostClient, type DotwireHostConfig, DotwireHostRoom, type DotwireRole, DotwireTokenSigner, type GetMessagesOptions, type HistoryMessage, type MintTokenOptions, type ModerationClassifier, ModerationQueue, type ModerationVerdict, type PendingModeration, type PostSendContext, PostSendError, type PresendContext, PresendRejectedError, PresendResult, type RedactMessageResponse, type RetentionResponse, type RoomEvent, type RoomHistoryResponse, type RoomMembersResponse, type SendMessageResult, type SendSystemMessageOptions, type StreamRoomEventsOptions, type TokenResponseOptions, type UserExport, type UserExportAuditEvent, type UserExportMessage, type UserRoleResponse, type UserRoomsResponse, type WebhookResult, mapErrorKind };