@fungi.computer/oyster 0.4.1 → 0.6.0

package/dist/channels/ids.d.ts

@@ -0,0 +1,8 @@
+/** Server- and widget-minted channel identities, shared by both Oyster hosts. */
+export declare const channelIds: Readonly<{
+    readonly binding: import("@fungi.computer/cairn").IdCodec<"channel", "binding", 1>;
+    readonly site: import("@fungi.computer/cairn").IdCodec<"channel", "site", 1>;
+    readonly endpoint: import("@fungi.computer/cairn").IdCodec<"channel", "endpoint", 1>;
+    readonly visitor: import("@fungi.computer/cairn").IdCodec<"channel", "visitor", 1>;
+    readonly message: import("@fungi.computer/cairn").IdCodec<"channel", "message", 1>;
+}>;

package/dist/channels/ids.js

@@ -0,0 +1,15 @@
+import { defineIdFamily } from "@fungi.computer/cairn/id";
+/** Server- and widget-minted channel identities, shared by both Oyster hosts. */
+export const channelIds = defineIdFamily({
+    family: "channel",
+    version: 1,
+    kinds: {
+        binding: { prefix: "chb" },
+        site: { prefix: "site_pk" },
+        /** The public, unguessable address of one incoming-events binding. */
+        endpoint: { prefix: "evt_ep" },
+        visitor: { prefix: "v" },
+        /** One visitor message; the widget mints it so a resend replays. */
+        message: { prefix: "msg" },
+    },
+});

package/dist/channels/visitor-channel.d.ts

@@ -0,0 +1,53 @@
+import { type ConversationBinding } from "./binding.js";
+import { type ChannelConversations, type ChannelWithdrawResult, type InboundEvent, type IntakeResult, type SessionDoor, type VisitorPendingPrompt, type VisitorReadOptions } from "./conversations.js";
+import type { ChannelVisitors, VisitorGrant } from "./visitors.js";
+/**
+ * Web visitor sequencing only. The host owns authorization, its admission
+ * receipt and the Session implementation; identity and conversations can live
+ * in different stores (and, in standalone, different Agents).
+ */
+export declare function createVisitorChannel(options: Readonly<{
+    binding: (bindingId: string) => ConversationBinding | null;
+    visitors: () => ChannelVisitors;
+    conversations: () => ChannelConversations;
+    sessionDoor: () => SessionDoor;
+    intake: (event: InboundEvent) => Promise<IntakeResult>;
+    acquireStream: (bindingId: string, visitorId: string, addressHash: string) => (() => void) | null;
+    now: () => number;
+}>): {
+    mint: (bindingId: string, siteKey: string, addressHash: string) => Promise<VisitorGrant>;
+    refresh: (bindingId: string, secret: string) => Promise<VisitorGrant>;
+    rotate: (bindingId: string, siteKey: string, token: string, addressHash: string) => Promise<VisitorGrant | Readonly<{
+        kind: "unauthorized";
+    }>>;
+    send: (bindingId: string, token: string, requestId: string, text: string) => Promise<IntakeResult | Readonly<{
+        kind: "unauthorized";
+    }>>;
+    withdraw: (bindingId: string, token: string, rawRequestId: string) => Promise<ChannelWithdrawResult | Readonly<{
+        kind: "unauthorized";
+    }> | Readonly<{
+        kind: "denied";
+        reason: "event_conflict" | "new_party_limit" | "banned";
+    }>>;
+    latestPending: (bindingId: string, token: string) => Promise<VisitorPendingPrompt | null | Readonly<{
+        kind: "unauthorized";
+    }>>;
+    open: (bindingId: string, token: string, read: VisitorReadOptions) => Promise<Readonly<{
+        kind: "session";
+        snapshot: string;
+    }> | Readonly<{
+        kind: "unauthorized";
+    }> | Readonly<{
+        kind: "denied";
+        reason: "new_party_limit" | "banned";
+    }>>;
+    watch: (bindingId: string, token: string, canRead: (visitorId: string) => Promise<boolean>) => Promise<Readonly<{
+        kind: "stream";
+        body: ReadableStream<Uint8Array>;
+    }> | Readonly<{
+        kind: "empty" | "unauthorized";
+    }> | Readonly<{
+        kind: "denied";
+        reason: "suspended" | "stream_limit";
+    }>>;
+};

package/dist/channels/visitor-channel.js

@@ -0,0 +1,124 @@
+import { partyLabel } from "./binding.js";
+import { channelRequestId, } from "./conversations.js";
+import { visitorMessageId, visitorRequestSchema } from "./visitor-request.js";
+/**
+ * Web visitor sequencing only. The host owns authorization, its admission
+ * receipt and the Session implementation; identity and conversations can live
+ * in different stores (and, in standalone, different Agents).
+ */
+export function createVisitorChannel(options) {
+    const active = (bindingId) => {
+        const binding = options.binding(bindingId);
+        return binding?.lifecycle === "active" &&
+            binding.selector.provider === "web"
+            ? binding
+            : null;
+    };
+    const authenticate = (bindingId, token) => options.visitors().authenticate(bindingId, token);
+    return {
+        mint: (bindingId, siteKey, addressHash) => options.visitors().mint(options.binding(bindingId), siteKey, addressHash),
+        refresh: (bindingId, secret) => options.visitors().refresh(options.binding(bindingId), secret),
+        rotate: async (bindingId, siteKey, token, addressHash) => {
+            const visitors = options.visitors();
+            const visitor = await visitors.authenticate(bindingId, token);
+            if (visitor === null)
+                return { kind: "unauthorized" };
+            visitors.forget(visitor.visitorId);
+            return await visitors.mint(options.binding(bindingId), siteKey, addressHash);
+        },
+        send: async (bindingId, token, requestId, text) => {
+            const visitor = await authenticate(bindingId, token);
+            if (visitor === null)
+                return { kind: "unauthorized" };
+            const { visitorId } = visitor;
+            return options.intake({
+                bindingId,
+                conversation: visitorId,
+                eventId: await visitorMessageId(requestId),
+                party: { kind: "visitor", visitorId },
+                text,
+                sourceRequestId: requestId,
+            });
+        },
+        withdraw: async (bindingId, token, rawRequestId) => {
+            const binding = active(bindingId);
+            const visitor = await authenticate(bindingId, token);
+            if (visitor === null || binding === null)
+                return { kind: "unauthorized" };
+            const { requestId } = visitorRequestSchema.parse({
+                requestId: rawRequestId,
+            });
+            const eventId = await visitorMessageId(requestId);
+            const conversations = options.conversations();
+            if (conversations.visitorEventConflict(bindingId, visitor.visitorId, eventId))
+                return { kind: "denied", reason: "event_conflict" };
+            const opened = await conversations.open(binding, visitor.visitorId, {
+                kind: "visitor",
+                visitorId: visitor.visitorId,
+            });
+            if (opened.kind === "denied")
+                return opened;
+            return options
+                .sessionDoor()
+                .withdraw(opened.conversation.sessionId, channelRequestId(binding.bindingId, eventId));
+        },
+        latestPending: async (bindingId, token) => {
+            const binding = active(bindingId);
+            const visitor = await authenticate(bindingId, token);
+            if (visitor === null || binding === null)
+                return { kind: "unauthorized" };
+            const { visitorId } = visitor;
+            const conversation = options.conversations().find(bindingId, visitorId);
+            if (conversation === null)
+                return null;
+            return await options.sessionDoor().latestPending(conversation.sessionId, {
+                id: visitorId,
+                name: partyLabel({ kind: "visitor", visitorId }),
+            });
+        },
+        open: async (bindingId, token, read) => {
+            const binding = active(bindingId);
+            const visitor = await authenticate(bindingId, token);
+            if (visitor === null || binding === null)
+                return { kind: "unauthorized" };
+            const { visitorId } = visitor;
+            const opened = await options.conversations().open(binding, visitorId, {
+                kind: "visitor",
+                visitorId,
+            });
+            if (opened.kind === "denied")
+                return opened;
+            return {
+                kind: "session",
+                snapshot: await options
+                    .sessionDoor()
+                    .participantDocument(opened.conversation.sessionId, visitorId, read),
+            };
+        },
+        watch: async (bindingId, token, canRead) => {
+            const visitor = await authenticate(bindingId, token);
+            if (visitor === null)
+                return { kind: "unauthorized" };
+            if (options.binding(bindingId)?.lifecycle !== "active")
+                return { kind: "denied", reason: "suspended" };
+            const { visitorId } = visitor;
+            const conversation = options.conversations().find(bindingId, visitorId);
+            if (conversation === null)
+                return { kind: "empty" };
+            const release = options.acquireStream(bindingId, visitorId, visitor.addressHash);
+            if (release === null)
+                return { kind: "denied", reason: "stream_limit" };
+            return {
+                kind: "stream",
+                body: await options
+                    .sessionDoor()
+                    .participantStream(conversation.sessionId, visitorId, {
+                    expiresAt: visitor.expiresAt,
+                    now: options.now,
+                    release,
+                    canRead: () => canRead(visitorId),
+                }),
+            };
+        },
+    };
+}

package/dist/channels/visitor-edge.d.ts

@@ -0,0 +1,115 @@
+import { Hono, type Context, type Env as HonoEnv } from "hono";
+import type { ChannelWithdrawResult, IntakeResult, VisitorPendingPrompt, VisitorReadOptions } from "./conversations.js";
+import { type VisitorGrant } from "./visitors.js";
+import type { Avatar } from "@fungi.computer/sprite/avatar";
+/** Public address facts the host supplies after looking up an embed site. */
+export type VisitorSiteAddress = Readonly<{
+    bindingId: string;
+}>;
+/** Embed-safe site chrome returned by the host after binding admission. */
+export type VisitorSiteFacts = Readonly<{
+    accent?: string;
+    name: string;
+    avatar: Avatar;
+    origins: readonly string[];
+}>;
+/** An opened host door, disposed after the edge has returned a response. */
+export type VisitorEdgeChannel = Readonly<{
+    [Symbol.dispose]: () => void;
+    readChannelSite: (input: Readonly<{
+        bindingId: string;
+        siteKey: string;
+    }>) => Promise<VisitorSiteFacts | null>;
+    mintChannelVisitor: (input: Readonly<{
+        bindingId: string;
+        siteKey: string;
+        addressHash: string;
+    }>) => Promise<VisitorGrant>;
+    refreshChannelVisitor: (input: Readonly<{
+        bindingId: string;
+        refreshSecret: string;
+    }>) => Promise<VisitorGrant>;
+    rotateChannelVisitor: (input: Readonly<{
+        bindingId: string;
+        siteKey: string;
+        accessToken: string;
+        addressHash: string;
+    }>) => Promise<VisitorGrant | Readonly<{
+        kind: "unauthorized";
+    }>>;
+    sendAsChannelVisitor: (input: Readonly<{
+        bindingId: string;
+        accessToken: string;
+        requestId: string;
+        text: string;
+    }>) => Promise<IntakeResult | Readonly<{
+        kind: "unauthorized";
+    }>>;
+    withdrawAsChannelVisitor: (input: Readonly<{
+        bindingId: string;
+        accessToken: string;
+        requestId: string;
+    }>) => Promise<ChannelWithdrawResult | Readonly<{
+        kind: "unauthorized";
+    }> | Readonly<{
+        kind: "denied";
+        reason: "event_conflict" | "new_party_limit" | "banned";
+    }>>;
+    latestPendingAsChannelVisitor: (input: Readonly<{
+        bindingId: string;
+        accessToken: string;
+    }>) => Promise<VisitorPendingPrompt | null | Readonly<{
+        kind: "unauthorized";
+    }>>;
+    watchAsChannelVisitor: (input: Readonly<{
+        bindingId: string;
+        accessToken: string;
+    }>) => Promise<Readonly<{
+        kind: "stream";
+        body: ReadableStream<Uint8Array>;
+    }> | Readonly<{
+        kind: "empty";
+    }> | Readonly<{
+        kind: "unauthorized";
+    }> | Readonly<{
+        kind: "denied";
+        reason: "suspended" | "stream_limit";
+    }>>;
+    openVisitorSession: (input: Readonly<{
+        bindingId: string;
+        accessToken: string;
+        options: VisitorReadOptions;
+    }>) => Promise<Readonly<{
+        kind: "session";
+        snapshot: string;
+    }> | Readonly<{
+        kind: "unauthorized";
+    }> | Readonly<{
+        kind: "denied";
+        reason: "new_party_limit" | "banned";
+    }>>;
+    readAsChannelVisitor: (input: Readonly<{
+        bindingId: string;
+        accessToken: string;
+    }>) => Promise<Readonly<{
+        kind: "view";
+        view: unknown;
+    }> | Readonly<{
+        kind: "unauthorized";
+    }>>;
+}>;
+/**
+ * Address lookup and mint/refresh use the site owner; conversation work must
+ * receive a verified visitor first. A host may route different visitors to
+ * different Agents without teaching the conversation core about its registry.
+ */
+export type VisitorEdgeHost<E extends HonoEnv, Site extends VisitorSiteAddress, Visitor extends object> = Readonly<{
+    resolveSite: (context: Context<E>, siteKey: string) => Promise<Site | null>;
+    openSite: (context: Context<E>, site: Site) => Promise<VisitorEdgeChannel>;
+    authenticateVisitor: (context: Context<E>, site: Site, token: string) => Promise<Visitor | null>;
+    openChannel: (context: Context<E>, site: Site, visitor: Visitor) => Promise<VisitorEdgeChannel>;
+    addressHash: (context: Context<E>) => Promise<string>;
+    assetPath: (kind: "widget" | "styles") => string;
+    onError: (error: Error, context: Context<E>) => Response | Promise<Response>;
+}>;
+export declare function createVisitorEdge<E extends HonoEnv, Site extends VisitorSiteAddress, Visitor extends object>(host: VisitorEdgeHost<E, Site, Visitor>): Hono<E>;