@polyester/sdk 0.0.0

package/dist/realtime/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":["#config","#getAuthHeaders","#sharedSubs","#channelKind","#emitSubscriptionError","#publicClient","#connectionHandlers","#privateClient","#emitConnectionTokenError","#createPublicClient","#hasAuth","#createPrivateClient","#assertChannelAuth","#ensurePrivateClient","#ensurePublicClient","#attachSubscriptionNow","#attachSubscriptionWhenLoaded","#ensureClientForChannel","#subscriptionOpts","#pendingTeardowns","#attachSubscription","#callErrorHandler","#disconnectClientIfIdle","#hasChannelsForKind","#teardownSubscription","#getOrCreateSubscription","#callConsumerHandler","#disconnect","#disconnectPrivate"],"sources":["../../src/realtime/client.ts"],"sourcesContent":["import { fromBinary, type DescMessage, type MessageShape } from \"@bufbuild/protobuf\";\nimport type {\n    Centrifuge,\n    SubscriptionErrorContext,\n    PublicationContext,\n    Subscription,\n} from \"centrifuge/build/protobuf\";\nimport type * as CentrifugeModule from \"centrifuge/build/protobuf\";\nimport {\n    createSdkSubscriptionErrorContext,\n    fromCentrifugeSubscriptionError,\n    type SdkSubscriptionErrorContext,\n} from \"../shared/subscription-errors.js\";\nimport { AuthenticationError, errorFromHttpStatus, InternalServerError } from \"../shared/errors.js\";\nimport { makeFetch } from \"../shared/transports.js\";\nimport { decodeProtoFrame } from \"../utils/streams.js\";\nimport type { ConnectChannelParams, PolyesterRealtime, SubscribeHandlers } from \"./types.js\";\n\nconst realtimeFetch = makeFetch();\n\ntype CentrifugeCtor = typeof CentrifugeModule.Centrifuge;\n\n// Centrifuge's protobuf build embeds the protobuf.js runtime (~300 KB minified).\n// Loading it lazily keeps it out of the eager module graph on both the server\n// (Cloudflare isolate cold start — SSR never opens a websocket) and the client\n// app shell; it is only fetched when the first subscription attaches.\nlet centrifugeCtorPromise: Promise<CentrifugeCtor> | null = null;\nlet loadedCentrifugeCtor: CentrifugeCtor | null = null;\nexport function __setRealtimeCentrifugeForTests(Centrifuge: CentrifugeCtor | null): void {\n    loadedCentrifugeCtor = Centrifuge;\n    centrifugeCtorPromise = Centrifuge ? Promise.resolve(Centrifuge) : null;\n}\n\nfunction loadCentrifuge(): Promise<CentrifugeCtor> {\n    if ((import.meta as { env?: { SSR?: boolean } }).env?.SSR) {\n        return Promise.reject(new Error(\"Realtime subscriptions are browser-only during SSR.\"));\n    }\n\n    centrifugeCtorPromise ??= import(\"centrifuge/build/protobuf\").then((mod) => {\n        loadedCentrifugeCtor = mod.Centrifuge;\n        return mod.Centrifuge;\n    });\n    return centrifugeCtorPromise;\n}\n\nexport interface RealtimeAuthRequest {\n    url: string | URL;\n    method: string;\n}\n\nexport interface RealtimeConfig {\n    wsUrl: string;\n    tokenEndpoint: string;\n    subscribeEndpoint: string;\n    getAuthHeaders?: (request: RealtimeAuthRequest) => Promise<HeadersInit> | HeadersInit;\n    hasAuth?: () => boolean;\n}\n\ntype ResolvedRealtimeConfig = Pick<\n    RealtimeConfig,\n    \"wsUrl\" | \"tokenEndpoint\" | \"subscribeEndpoint\"\n> & {\n    getAuthHeaders: (request: RealtimeAuthRequest) => Promise<HeadersInit> | HeadersInit;\n    hasAuth: () => boolean;\n};\n\nexport type { ConnectChannelParams, PolyesterRealtime, SubscribeHandlers } from \"./types.js\";\n\ntype ConnectionHandler = { onConnected?: () => void; onDisconnected?: () => void };\ntype PublicationHandler<T = unknown> = (data: T) => void;\ntype ErrorHandler = (ctx: SdkSubscriptionErrorContext) => void;\ntype RealtimeClientKind = \"public\" | \"private\";\n\ninterface SharedSubscription {\n    channel: string;\n    sub: Subscription | null;\n    client: Centrifuge | null;\n    attachmentEpoch: number;\n    consumers: number;\n    subscriptionEpoch: number;\n    publicationHandlers: Set<PublicationHandler>;\n    subscribedHandlers: Set<(epoch: number) => void>;\n    unsubscribedHandlers: Set<() => void>;\n    errorHandlers: Set<ErrorHandler>;\n}\n\n/**\n * Shared Centrifuge realtime client that multiplexes public and private protobuf subscriptions across SDK services.\n */\nexport class RealtimeClient implements PolyesterRealtime {\n    #publicClient: Centrifuge | null = null;\n    #privateClient: Centrifuge | null = null;\n    #connectionHandlers = new Set<ConnectionHandler>();\n    #sharedSubs = new Map<string, SharedSubscription>();\n    #pendingTeardowns = new Map<string, SharedSubscription>();\n    readonly #config: ResolvedRealtimeConfig;\n\n    constructor(config: RealtimeConfig) {\n        this.#config = {\n            wsUrl: config.wsUrl,\n            tokenEndpoint: config.tokenEndpoint,\n            subscribeEndpoint: config.subscribeEndpoint,\n            getAuthHeaders: config.getAuthHeaders ?? (() => ({})),\n            hasAuth: config.hasAuth ?? (() => false),\n        };\n    }\n\n    async #getAuthHeaders(request: RealtimeAuthRequest): Promise<HeadersInit> {\n        return this.#config.getAuthHeaders(request);\n    }\n\n    #emitSubscriptionError(shared: SharedSubscription, type: string, error: unknown): void {\n        const ctx = createSdkSubscriptionErrorContext(shared.channel, type, error);\n        for (const handler of shared.errorHandlers) {\n            handler(ctx);\n        }\n    }\n\n    #emitConnectionTokenError(error: unknown): void {\n        for (const shared of this.#sharedSubs.values()) {\n            if (this.#channelKind(shared.channel) === \"private\") {\n                this.#emitSubscriptionError(shared, \"connection_token\", error);\n            }\n        }\n    }\n\n    #subscriptionOpts(shared: SharedSubscription, attachmentEpoch: number) {\n        if (this.#channelKind(shared.channel) !== \"private\") return undefined;\n        return {\n            getToken: async () => {\n                try {\n                    const url = new URL(this.#config.subscribeEndpoint);\n                    url.searchParams.set(\"channel\", shared.channel);\n                    const headers = await this.#getAuthHeaders({ url, method: \"GET\" });\n                    const res = await realtimeFetch(url, { headers });\n                    if (!res.ok) {\n                        throw errorFromHttpStatus(\n                            res.status,\n                            `Failed to fetch subscription token: ${res.status}`,\n                        );\n                    }\n                    const json = (await res.json()) as { token?: string };\n                    if (!json?.token) {\n                        throw new InternalServerError(\"Subscription token response had no token\");\n                    }\n                    return json.token;\n                } catch (error) {\n                    if (shared.attachmentEpoch === attachmentEpoch) {\n                        this.#emitSubscriptionError(shared, \"subscription_token\", error);\n                    }\n                    throw error;\n                }\n            },\n        };\n    }\n\n    #hasAuth(): boolean {\n        return this.#config.hasAuth();\n    }\n\n    #channelKind(channel: string): RealtimeClientKind {\n        return channel.startsWith(\"private:\") ? \"private\" : \"public\";\n    }\n\n    #createPublicClient(Centrifuge: CentrifugeCtor): Centrifuge {\n        const client = new Centrifuge(this.#config.wsUrl);\n        this.#publicClient = client;\n\n        client.on(\"connected\", () => {\n            if (this.#publicClient !== client) return;\n            for (const h of this.#connectionHandlers) h.onConnected?.();\n        });\n        client.on(\"disconnected\", () => {\n            if (this.#publicClient !== client) return;\n            for (const h of this.#connectionHandlers) h.onDisconnected?.();\n        });\n\n        client.connect();\n        return client;\n    }\n\n    #createPrivateClient(Centrifuge: CentrifugeCtor): Centrifuge {\n        let client: Centrifuge;\n        const opts = {\n            getToken: async () => {\n                try {\n                    const headers = await this.#getAuthHeaders({\n                        url: this.#config.tokenEndpoint,\n                        method: \"GET\",\n                    });\n                    const res = await realtimeFetch(this.#config.tokenEndpoint, {\n                        headers,\n                    });\n                    if (!res.ok) {\n                        throw errorFromHttpStatus(\n                            res.status,\n                            `Failed to fetch connection token: ${res.status}`,\n                        );\n                    }\n                    const json = (await res.json()) as { token?: string };\n                    if (!json?.token) {\n                        throw new InternalServerError(\"Connection token response had no token\");\n                    }\n                    return json.token;\n                } catch (error) {\n                    if (this.#privateClient === client) {\n                        this.#emitConnectionTokenError(error);\n                    }\n                    throw error;\n                }\n            },\n        };\n\n        client = new Centrifuge(this.#config.wsUrl, opts);\n        this.#privateClient = client;\n\n        client.on(\"connected\", () => {\n            if (this.#privateClient !== client) return;\n            for (const h of this.#connectionHandlers) h.onConnected?.();\n        });\n        client.on(\"disconnected\", () => {\n            if (this.#privateClient !== client) return;\n            for (const h of this.#connectionHandlers) h.onDisconnected?.();\n        });\n\n        client.connect();\n        return client;\n    }\n\n    #ensurePublicClient(Centrifuge: CentrifugeCtor): Centrifuge {\n        return this.#publicClient ?? this.#createPublicClient(Centrifuge);\n    }\n\n    #ensurePrivateClient(Centrifuge: CentrifugeCtor): Centrifuge {\n        if (!this.#hasAuth()) {\n            throw new AuthenticationError(\n                \"Cannot create authenticated realtime client without authentication\",\n            );\n        }\n        return this.#privateClient ?? this.#createPrivateClient(Centrifuge);\n    }\n\n    #assertChannelAuth(channel: string): void {\n        if (this.#channelKind(channel) === \"private\" && !this.#hasAuth()) {\n            throw new AuthenticationError(\n                `Cannot subscribe to private channel \"${channel}\" without authentication`,\n            );\n        }\n    }\n\n    #ensureClientForChannel(Centrifuge: CentrifugeCtor, channel: string): Centrifuge {\n        this.#assertChannelAuth(channel);\n        if (this.#channelKind(channel) === \"private\") {\n            return this.#ensurePrivateClient(Centrifuge);\n        }\n\n        return this.#ensurePublicClient(Centrifuge);\n    }\n\n    #attachSubscription(shared: SharedSubscription): void {\n        if (shared.sub) return;\n\n        // Auth failures must surface synchronously to subscribe() callers, as\n        // they did when centrifuge was imported statically.\n        this.#assertChannelAuth(shared.channel);\n\n        const attachmentEpoch = shared.attachmentEpoch + 1;\n        shared.attachmentEpoch = attachmentEpoch;\n\n        // Once the transport module is loaded, attachment stays fully\n        // synchronous — only the very first attach pays the dynamic import.\n        if (loadedCentrifugeCtor) {\n            this.#attachSubscriptionNow(loadedCentrifugeCtor, shared, attachmentEpoch);\n            return;\n        }\n        void this.#attachSubscriptionWhenLoaded(shared, attachmentEpoch);\n    }\n\n    async #attachSubscriptionWhenLoaded(\n        shared: SharedSubscription,\n        attachmentEpoch: number,\n    ): Promise<void> {\n        let Centrifuge: CentrifugeCtor;\n        try {\n            Centrifuge = await loadCentrifuge();\n        } catch (error) {\n            if (shared.attachmentEpoch !== attachmentEpoch) return;\n            if (this.#sharedSubs.get(shared.channel) === shared) {\n                this.#sharedSubs.delete(shared.channel);\n            }\n            this.#emitSubscriptionError(shared, \"transport_load\", error);\n            return;\n        }\n\n        // The subscription may have been torn down or re-attached while the\n        // transport module was loading.\n        if (shared.attachmentEpoch !== attachmentEpoch || shared.sub) return;\n        if (this.#sharedSubs.get(shared.channel) !== shared) return;\n\n        try {\n            this.#attachSubscriptionNow(Centrifuge, shared, attachmentEpoch);\n        } catch (error) {\n            this.#sharedSubs.delete(shared.channel);\n            this.#emitSubscriptionError(shared, \"auth\", error);\n        }\n    }\n\n    #attachSubscriptionNow(\n        Centrifuge: CentrifugeCtor,\n        shared: SharedSubscription,\n        attachmentEpoch: number,\n    ): void {\n        const client = this.#ensureClientForChannel(Centrifuge, shared.channel);\n\n        const sub = client.newSubscription(\n            shared.channel,\n            this.#subscriptionOpts(shared, attachmentEpoch),\n        );\n        shared.sub = sub;\n        shared.client = client;\n\n        sub.on(\"publication\", (ctx: PublicationContext) => {\n            if (shared.sub !== sub || shared.attachmentEpoch !== attachmentEpoch) return;\n            for (const handler of shared.publicationHandlers) handler(ctx.data);\n        });\n        sub.on(\"subscribed\", () => {\n            if (shared.sub !== sub || shared.attachmentEpoch !== attachmentEpoch) return;\n            const subscriptionEpoch = ++shared.subscriptionEpoch;\n            for (const handler of shared.subscribedHandlers) handler(subscriptionEpoch);\n        });\n        sub.on(\"unsubscribed\", () => {\n            if (shared.sub !== sub || shared.attachmentEpoch !== attachmentEpoch) return;\n            for (const handler of shared.unsubscribedHandlers) handler();\n        });\n        sub.on(\"error\", (ctx: SubscriptionErrorContext) => {\n            if (shared.sub !== sub || shared.attachmentEpoch !== attachmentEpoch) return;\n            const sdkCtx = fromCentrifugeSubscriptionError(ctx);\n            for (const handler of shared.errorHandlers) handler(sdkCtx);\n        });\n\n        sub.subscribe();\n    }\n\n    #getOrCreateSubscription(channel: string): SharedSubscription {\n        const existing = this.#sharedSubs.get(channel);\n        if (existing) return existing;\n\n        const pending = this.#pendingTeardowns.get(channel);\n        if (pending) {\n            this.#pendingTeardowns.delete(channel);\n            this.#sharedSubs.set(channel, pending);\n            if (!pending.sub) {\n                this.#attachSubscription(pending);\n            } else if (pending.sub.state !== \"subscribed\") {\n                pending.sub.subscribe();\n            }\n            return pending;\n        }\n\n        const shared: SharedSubscription = {\n            channel,\n            sub: null,\n            client: null,\n            attachmentEpoch: 0,\n            consumers: 0,\n            subscriptionEpoch: 0,\n            publicationHandlers: new Set(),\n            subscribedHandlers: new Set(),\n            unsubscribedHandlers: new Set(),\n            errorHandlers: new Set(),\n        };\n\n        this.#sharedSubs.set(channel, shared);\n        try {\n            this.#attachSubscription(shared);\n        } catch (error) {\n            this.#sharedSubs.delete(channel);\n            throw error;\n        }\n        return shared;\n    }\n\n    #callErrorHandler(handler: ErrorHandler | undefined, ctx: SdkSubscriptionErrorContext): void {\n        if (!handler) return;\n\n        try {\n            handler(ctx);\n        } catch {\n            // Keep error reporting isolated from other subscription consumers.\n        }\n    }\n\n    #callConsumerHandler(\n        channel: string,\n        type: string,\n        handler: () => void,\n        onError?: ErrorHandler,\n    ): void {\n        try {\n            handler();\n        } catch (error) {\n            this.#callErrorHandler(\n                onError,\n                createSdkSubscriptionErrorContext(channel, type, error),\n            );\n        }\n    }\n\n    #teardownSubscription(shared: SharedSubscription): void {\n        const sub = shared.sub;\n        const client = shared.client;\n        const kind = this.#channelKind(shared.channel);\n        shared.sub = null;\n        shared.client = null;\n        shared.attachmentEpoch++;\n        if (!sub) return;\n\n        try {\n            if (sub.state !== \"unsubscribed\") {\n                sub.unsubscribe();\n            }\n        } catch {\n            // noop\n        }\n        try {\n            client?.removeSubscription?.(sub);\n        } catch {\n            // noop\n        }\n        this.#disconnectClientIfIdle(kind);\n    }\n\n    #hasChannelsForKind(kind: RealtimeClientKind): boolean {\n        for (const shared of this.#sharedSubs.values()) {\n            if (this.#channelKind(shared.channel) === kind) return true;\n        }\n        for (const shared of this.#pendingTeardowns.values()) {\n            if (this.#channelKind(shared.channel) === kind) return true;\n        }\n        return false;\n    }\n\n    #disconnectClientIfIdle(kind: RealtimeClientKind): void {\n        if (this.#hasChannelsForKind(kind)) return;\n\n        const client = kind === \"private\" ? this.#privateClient : this.#publicClient;\n        if (kind === \"private\") {\n            this.#privateClient = null;\n        } else {\n            this.#publicClient = null;\n        }\n\n        try {\n            client?.disconnect();\n        } catch {\n            // noop\n        }\n    }\n\n    #disconnect(): void {\n        const publicClient = this.#publicClient;\n        const privateClient = this.#privateClient;\n\n        this.#pendingTeardowns.clear();\n        this.#sharedSubs.clear();\n        this.#publicClient = null;\n        this.#privateClient = null;\n\n        try {\n            publicClient?.disconnect();\n        } catch {\n            // noop\n        }\n        try {\n            privateClient?.disconnect();\n        } catch {\n            // noop\n        }\n        this.#connectionHandlers.clear();\n    }\n\n    #disconnectPrivate(): void {\n        const privateClient = this.#privateClient;\n        this.#privateClient = null;\n\n        for (const [channel, shared] of this.#sharedSubs) {\n            if (this.#channelKind(channel) !== \"private\") continue;\n            this.#sharedSubs.delete(channel);\n            this.#teardownSubscription(shared);\n        }\n        for (const [channel, shared] of this.#pendingTeardowns) {\n            if (this.#channelKind(channel) !== \"private\") continue;\n            this.#pendingTeardowns.delete(channel);\n            this.#teardownSubscription(shared);\n        }\n\n        try {\n            privateClient?.disconnect();\n        } catch {\n            // noop\n        }\n    }\n\n    /**\n     * Subscribes to a realtime channel and returns an unsubscribe function.\n     */\n    subscribe<T>(channel: string, handlers: SubscribeHandlers<T>): () => void {\n        const shared = this.#getOrCreateSubscription(channel);\n        shared.consumers++;\n\n        const publicationHandler = handlers.onPublication;\n        const errorHandler = handlers.onError;\n        const subscribedHandler = handlers.onSubscribed;\n        const unsubscribedHandler = handlers.onUnsubscribed;\n\n        const onError: ErrorHandler | undefined = errorHandler\n            ? (ctx) => this.#callErrorHandler(errorHandler, ctx)\n            : undefined;\n        const onPub: PublicationHandler = (data) => {\n            this.#callConsumerHandler(\n                channel,\n                \"publication_handler\",\n                () => publicationHandler(data as T),\n                onError,\n            );\n        };\n        let lastSubscribedEpoch = -1;\n        const onSubscribed = subscribedHandler\n            ? (subscriptionEpoch: number) => {\n                  if (subscriptionEpoch <= lastSubscribedEpoch) return;\n                  lastSubscribedEpoch = subscriptionEpoch;\n                  this.#callConsumerHandler(\n                      channel,\n                      \"subscribed_handler\",\n                      subscribedHandler,\n                      onError,\n                  );\n              }\n            : undefined;\n        const onUnsubscribed = unsubscribedHandler\n            ? () =>\n                  this.#callConsumerHandler(\n                      channel,\n                      \"unsubscribed_handler\",\n                      unsubscribedHandler,\n                      onError,\n                  )\n            : undefined;\n\n        shared.publicationHandlers.add(onPub);\n\n        if (onSubscribed) shared.subscribedHandlers.add(onSubscribed);\n        if (onUnsubscribed) shared.unsubscribedHandlers.add(onUnsubscribed);\n        if (onError) shared.errorHandlers.add(onError);\n\n        let closed = false;\n        if (onSubscribed && shared.sub?.state === \"subscribed\") {\n            const subscriptionEpoch = shared.subscriptionEpoch;\n            queueMicrotask(() => {\n                if (closed || shared.sub?.state !== \"subscribed\") return;\n                onSubscribed(subscriptionEpoch);\n            });\n        }\n\n        return () => {\n            if (closed) return;\n            closed = true;\n\n            shared.publicationHandlers.delete(onPub);\n            if (onSubscribed) shared.subscribedHandlers.delete(onSubscribed);\n            if (onUnsubscribed) shared.unsubscribedHandlers.delete(onUnsubscribed);\n            if (onError) shared.errorHandlers.delete(onError);\n\n            shared.consumers--;\n            if (shared.consumers <= 0) {\n                const currentShared = this.#sharedSubs.get(channel);\n                if (currentShared !== shared) return;\n\n                this.#sharedSubs.delete(channel);\n                this.#pendingTeardowns.set(channel, shared);\n\n                queueMicrotask(() => {\n                    if (this.#pendingTeardowns.get(channel) !== shared) return;\n                    this.#pendingTeardowns.delete(channel);\n\n                    this.#teardownSubscription(shared);\n\n                    if (this.#sharedSubs.size === 0 && this.#pendingTeardowns.size === 0) {\n                        this.#disconnect();\n                    }\n                });\n            }\n        };\n    }\n\n    /**\n     * Connects to a realtime channel with a custom message decoder.\n     */\n    connectChannel<T extends DescMessage>(params: ConnectChannelParams<T>): () => void {\n        return this.subscribe<Uint8Array>(params.channel, {\n            onPublication: (data) => {\n                let decoded: MessageShape<T>;\n                try {\n                    decoded = fromBinary(params.schema, data);\n                } catch (error) {\n                    this.#callErrorHandler(\n                        params.onError,\n                        createSdkSubscriptionErrorContext(params.channel, \"decode\", error),\n                    );\n                    return;\n                }\n                params.onPublication(decoded);\n            },\n            onSubscribed: params.onConnected,\n            onUnsubscribed: params.onDisconnected,\n            onError: params.onError,\n        });\n    }\n\n    /**\n     * Connects to a realtime channel that emits protobuf messages.\n     */\n    connectProtoChannel<T extends DescMessage>(params: ConnectChannelParams<T>): () => void {\n        return this.subscribe<Uint8Array | MessageShape<T>>(params.channel, {\n            onPublication: (data) => {\n                let msg: MessageShape<T> | null;\n                try {\n                    msg = decodeProtoFrame(params.schema, data);\n                } catch (error) {\n                    this.#callErrorHandler(\n                        params.onError,\n                        createSdkSubscriptionErrorContext(params.channel, \"decode\", error),\n                    );\n                    return;\n                }\n                if (!msg) {\n                    this.#callErrorHandler(\n                        params.onError,\n                        createSdkSubscriptionErrorContext(\n                            params.channel,\n                            \"decode\",\n                            \"Unable to decode protobuf frame\",\n                        ),\n                    );\n                    return;\n                }\n                params.onPublication(msg);\n            },\n            onSubscribed: params.onConnected,\n            onUnsubscribed: params.onDisconnected,\n            onError: params.onError,\n        });\n    }\n\n    /**\n     * Disconnects the realtime client from all active channels.\n     */\n    disconnect(): void {\n        this.#disconnect();\n    }\n\n    /**\n     * Disconnects authenticated realtime state without touching public channels.\n     */\n    disconnectPrivate(): void {\n        this.#disconnectPrivate();\n    }\n\n    get isConnected(): boolean {\n        return this.#publicClient !== null || this.#privateClient !== null;\n    }\n\n    get activeChannels(): number {\n        return this.#sharedSubs.size;\n    }\n\n    get totalConsumers(): number {\n        let total = 0;\n        for (const shared of this.#sharedSubs.values()) {\n            total += shared.consumers;\n        }\n        return total;\n    }\n}\n"],"mappings":";;;;;;AAkBA,MAAM,gBAAgB,UAAU;AAQhC,IAAI,wBAAwD;AAC5D,IAAI,uBAA8C;AAMlD,SAAS,iBAA0C;CAC/C,IAAK,YAA4C,KAAK,KAClD,OAAO,QAAQ,uBAAO,IAAI,MAAM,qDAAqD,CAAC;CAG1F,0BAA0B,OAAO,4BAA4B,CAAC,MAAM,QAAQ;EACxE,uBAAuB,IAAI;EAC3B,OAAO,IAAI;CACf,CAAC;CACD,OAAO;AACX;;;;AA8CA,IAAa,iBAAb,MAAyD;CACrD,gBAAmC;CACnC,iBAAoC;CACpC,sCAAsB,IAAI,IAAuB;CACjD,8BAAc,IAAI,IAAgC;CAClD,oCAAoB,IAAI,IAAgC;CACxD;CAEA,YAAY,QAAwB;EAChC,KAAKA,UAAU;GACX,OAAO,OAAO;GACd,eAAe,OAAO;GACtB,mBAAmB,OAAO;GAC1B,gBAAgB,OAAO,0BAA0B,CAAC;GAClD,SAAS,OAAO,kBAAkB;EACtC;CACJ;CAEA,MAAMC,gBAAgB,SAAoD;EACtE,OAAO,KAAKD,QAAQ,eAAe,OAAO;CAC9C;CAEA,uBAAuB,QAA4B,MAAc,OAAsB;EACnF,MAAM,MAAM,kCAAkC,OAAO,SAAS,MAAM,KAAK;EACzE,KAAK,MAAM,WAAW,OAAO,eACzB,QAAQ,GAAG;CAEnB;CAEA,0BAA0B,OAAsB;EAC5C,KAAK,MAAM,UAAU,KAAKE,YAAY,OAAO,GACzC,IAAI,KAAKC,aAAa,OAAO,OAAO,MAAM,WACtC,KAAKC,uBAAuB,QAAQ,oBAAoB,KAAK;CAGzE;CAEA,kBAAkB,QAA4B,iBAAyB;EACnE,IAAI,KAAKD,aAAa,OAAO,OAAO,MAAM,WAAW,OAAO,KAAA;EAC5D,OAAO,EACH,UAAU,YAAY;GAClB,IAAI;IACA,MAAM,MAAM,IAAI,IAAI,KAAKH,QAAQ,iBAAiB;IAClD,IAAI,aAAa,IAAI,WAAW,OAAO,OAAO;IAC9C,MAAM,UAAU,MAAM,KAAKC,gBAAgB;KAAE;KAAK,QAAQ;IAAM,CAAC;IACjE,MAAM,MAAM,MAAM,cAAc,KAAK,EAAE,QAAQ,CAAC;IAChD,IAAI,CAAC,IAAI,IACL,MAAM,oBACF,IAAI,QACJ,uCAAuC,IAAI,QAC/C;IAEJ,MAAM,OAAQ,MAAM,IAAI,KAAK;IAC7B,IAAI,CAAC,MAAM,OACP,MAAM,IAAI,oBAAoB,0CAA0C;IAE5E,OAAO,KAAK;GAChB,SAAS,OAAO;IACZ,IAAI,OAAO,oBAAoB,iBAC3B,KAAKG,uBAAuB,QAAQ,sBAAsB,KAAK;IAEnE,MAAM;GACV;EACJ,EACJ;CACJ;CAEA,WAAoB;EAChB,OAAO,KAAKJ,QAAQ,QAAQ;CAChC;CAEA,aAAa,SAAqC;EAC9C,OAAO,QAAQ,WAAW,UAAU,IAAI,YAAY;CACxD;CAEA,oBAAoB,YAAwC;EACxD,MAAM,SAAS,IAAI,WAAW,KAAKA,QAAQ,KAAK;EAChD,KAAKK,gBAAgB;EAErB,OAAO,GAAG,mBAAmB;GACzB,IAAI,KAAKA,kBAAkB,QAAQ;GACnC,KAAK,MAAM,KAAK,KAAKC,qBAAqB,EAAE,cAAc;EAC9D,CAAC;EACD,OAAO,GAAG,sBAAsB;GAC5B,IAAI,KAAKD,kBAAkB,QAAQ;GACnC,KAAK,MAAM,KAAK,KAAKC,qBAAqB,EAAE,iBAAiB;EACjE,CAAC;EAED,OAAO,QAAQ;EACf,OAAO;CACX;CAEA,qBAAqB,YAAwC;EACzD,IAAI;EA+BJ,SAAS,IAAI,WAAW,KAAKN,QAAQ,OAAO,EA7BxC,UAAU,YAAY;GAClB,IAAI;IACA,MAAM,UAAU,MAAM,KAAKC,gBAAgB;KACvC,KAAK,KAAKD,QAAQ;KAClB,QAAQ;IACZ,CAAC;IACD,MAAM,MAAM,MAAM,cAAc,KAAKA,QAAQ,eAAe,EACxD,QACJ,CAAC;IACD,IAAI,CAAC,IAAI,IACL,MAAM,oBACF,IAAI,QACJ,qCAAqC,IAAI,QAC7C;IAEJ,MAAM,OAAQ,MAAM,IAAI,KAAK;IAC7B,IAAI,CAAC,MAAM,OACP,MAAM,IAAI,oBAAoB,wCAAwC;IAE1E,OAAO,KAAK;GAChB,SAAS,OAAO;IACZ,IAAI,KAAKO,mBAAmB,QACxB,KAAKC,0BAA0B,KAAK;IAExC,MAAM;GACV;EACJ,EAG2C,CAAC;EAChD,KAAKD,iBAAiB;EAEtB,OAAO,GAAG,mBAAmB;GACzB,IAAI,KAAKA,mBAAmB,QAAQ;GACpC,KAAK,MAAM,KAAK,KAAKD,qBAAqB,EAAE,cAAc;EAC9D,CAAC;EACD,OAAO,GAAG,sBAAsB;GAC5B,IAAI,KAAKC,mBAAmB,QAAQ;GACpC,KAAK,MAAM,KAAK,KAAKD,qBAAqB,EAAE,iBAAiB;EACjE,CAAC;EAED,OAAO,QAAQ;EACf,OAAO;CACX;CAEA,oBAAoB,YAAwC;EACxD,OAAO,KAAKD,iBAAiB,KAAKI,oBAAoB,UAAU;CACpE;CAEA,qBAAqB,YAAwC;EACzD,IAAI,CAAC,KAAKC,SAAS,GACf,MAAM,IAAI,oBACN,oEACJ;EAEJ,OAAO,KAAKH,kBAAkB,KAAKI,qBAAqB,UAAU;CACtE;CAEA,mBAAmB,SAAuB;EACtC,IAAI,KAAKR,aAAa,OAAO,MAAM,aAAa,CAAC,KAAKO,SAAS,GAC3D,MAAM,IAAI,oBACN,wCAAwC,QAAQ,yBACpD;CAER;CAEA,wBAAwB,YAA4B,SAA6B;EAC7E,KAAKE,mBAAmB,OAAO;EAC/B,IAAI,KAAKT,aAAa,OAAO,MAAM,WAC/B,OAAO,KAAKU,qBAAqB,UAAU;EAG/C,OAAO,KAAKC,oBAAoB,UAAU;CAC9C;CAEA,oBAAoB,QAAkC;EAClD,IAAI,OAAO,KAAK;EAIhB,KAAKF,mBAAmB,OAAO,OAAO;EAEtC,MAAM,kBAAkB,OAAO,kBAAkB;EACjD,OAAO,kBAAkB;EAIzB,IAAI,sBAAsB;GACtB,KAAKG,uBAAuB,sBAAsB,QAAQ,eAAe;GACzE;EACJ;EACA,KAAUC,8BAA8B,QAAQ,eAAe;CACnE;CAEA,MAAMA,8BACF,QACA,iBACa;EACb,IAAI;EACJ,IAAI;GACA,aAAa,MAAM,eAAe;EACtC,SAAS,OAAO;GACZ,IAAI,OAAO,oBAAoB,iBAAiB;GAChD,IAAI,KAAKd,YAAY,IAAI,OAAO,OAAO,MAAM,QACzC,KAAKA,YAAY,OAAO,OAAO,OAAO;GAE1C,KAAKE,uBAAuB,QAAQ,kBAAkB,KAAK;GAC3D;EACJ;EAIA,IAAI,OAAO,oBAAoB,mBAAmB,OAAO,KAAK;EAC9D,IAAI,KAAKF,YAAY,IAAI,OAAO,OAAO,MAAM,QAAQ;EAErD,IAAI;GACA,KAAKa,uBAAuB,YAAY,QAAQ,eAAe;EACnE,SAAS,OAAO;GACZ,KAAKb,YAAY,OAAO,OAAO,OAAO;GACtC,KAAKE,uBAAuB,QAAQ,QAAQ,KAAK;EACrD;CACJ;CAEA,uBACI,YACA,QACA,iBACI;EACJ,MAAM,SAAS,KAAKa,wBAAwB,YAAY,OAAO,OAAO;EAEtE,MAAM,MAAM,OAAO,gBACf,OAAO,SACP,KAAKC,kBAAkB,QAAQ,eAAe,CAClD;EACA,OAAO,MAAM;EACb,OAAO,SAAS;EAEhB,IAAI,GAAG,gBAAgB,QAA4B;GAC/C,IAAI,OAAO,QAAQ,OAAO,OAAO,oBAAoB,iBAAiB;GACtE,KAAK,MAAM,WAAW,OAAO,qBAAqB,QAAQ,IAAI,IAAI;EACtE,CAAC;EACD,IAAI,GAAG,oBAAoB;GACvB,IAAI,OAAO,QAAQ,OAAO,OAAO,oBAAoB,iBAAiB;GACtE,MAAM,oBAAoB,EAAE,OAAO;GACnC,KAAK,MAAM,WAAW,OAAO,oBAAoB,QAAQ,iBAAiB;EAC9E,CAAC;EACD,IAAI,GAAG,sBAAsB;GACzB,IAAI,OAAO,QAAQ,OAAO,OAAO,oBAAoB,iBAAiB;GACtE,KAAK,MAAM,WAAW,OAAO,sBAAsB,QAAQ;EAC/D,CAAC;EACD,IAAI,GAAG,UAAU,QAAkC;GAC/C,IAAI,OAAO,QAAQ,OAAO,OAAO,oBAAoB,iBAAiB;GACtE,MAAM,SAAS,gCAAgC,GAAG;GAClD,KAAK,MAAM,WAAW,OAAO,eAAe,QAAQ,MAAM;EAC9D,CAAC;EAED,IAAI,UAAU;CAClB;CAEA,yBAAyB,SAAqC;EAC1D,MAAM,WAAW,KAAKhB,YAAY,IAAI,OAAO;EAC7C,IAAI,UAAU,OAAO;EAErB,MAAM,UAAU,KAAKiB,kBAAkB,IAAI,OAAO;EAClD,IAAI,SAAS;GACT,KAAKA,kBAAkB,OAAO,OAAO;GACrC,KAAKjB,YAAY,IAAI,SAAS,OAAO;GACrC,IAAI,CAAC,QAAQ,KACT,KAAKkB,oBAAoB,OAAO;QAC7B,IAAI,QAAQ,IAAI,UAAU,cAC7B,QAAQ,IAAI,UAAU;GAE1B,OAAO;EACX;EAEA,MAAM,SAA6B;GAC/B;GACA,KAAK;GACL,QAAQ;GACR,iBAAiB;GACjB,WAAW;GACX,mBAAmB;GACnB,qCAAqB,IAAI,IAAI;GAC7B,oCAAoB,IAAI,IAAI;GAC5B,sCAAsB,IAAI,IAAI;GAC9B,+BAAe,IAAI,IAAI;EAC3B;EAEA,KAAKlB,YAAY,IAAI,SAAS,MAAM;EACpC,IAAI;GACA,KAAKkB,oBAAoB,MAAM;EACnC,SAAS,OAAO;GACZ,KAAKlB,YAAY,OAAO,OAAO;GAC/B,MAAM;EACV;EACA,OAAO;CACX;CAEA,kBAAkB,SAAmC,KAAwC;EACzF,IAAI,CAAC,SAAS;EAEd,IAAI;GACA,QAAQ,GAAG;EACf,QAAQ,CAER;CACJ;CAEA,qBACI,SACA,MACA,SACA,SACI;EACJ,IAAI;GACA,QAAQ;EACZ,SAAS,OAAO;GACZ,KAAKmB,kBACD,SACA,kCAAkC,SAAS,MAAM,KAAK,CAC1D;EACJ;CACJ;CAEA,sBAAsB,QAAkC;EACpD,MAAM,MAAM,OAAO;EACnB,MAAM,SAAS,OAAO;EACtB,MAAM,OAAO,KAAKlB,aAAa,OAAO,OAAO;EAC7C,OAAO,MAAM;EACb,OAAO,SAAS;EAChB,OAAO;EACP,IAAI,CAAC,KAAK;EAEV,IAAI;GACA,IAAI,IAAI,UAAU,gBACd,IAAI,YAAY;EAExB,QAAQ,CAER;EACA,IAAI;GACA,QAAQ,qBAAqB,GAAG;EACpC,QAAQ,CAER;EACA,KAAKmB,wBAAwB,IAAI;CACrC;CAEA,oBAAoB,MAAmC;EACnD,KAAK,MAAM,UAAU,KAAKpB,YAAY,OAAO,GACzC,IAAI,KAAKC,aAAa,OAAO,OAAO,MAAM,MAAM,OAAO;EAE3D,KAAK,MAAM,UAAU,KAAKgB,kBAAkB,OAAO,GAC/C,IAAI,KAAKhB,aAAa,OAAO,OAAO,MAAM,MAAM,OAAO;EAE3D,OAAO;CACX;CAEA,wBAAwB,MAAgC;EACpD,IAAI,KAAKoB,oBAAoB,IAAI,GAAG;EAEpC,MAAM,SAAS,SAAS,YAAY,KAAKhB,iBAAiB,KAAKF;EAC/D,IAAI,SAAS,WACT,KAAKE,iBAAiB;OAEtB,KAAKF,gBAAgB;EAGzB,IAAI;GACA,QAAQ,WAAW;EACvB,QAAQ,CAER;CACJ;CAEA,cAAoB;EAChB,MAAM,eAAe,KAAKA;EAC1B,MAAM,gBAAgB,KAAKE;EAE3B,KAAKY,kBAAkB,MAAM;EAC7B,KAAKjB,YAAY,MAAM;EACvB,KAAKG,gBAAgB;EACrB,KAAKE,iBAAiB;EAEtB,IAAI;GACA,cAAc,WAAW;EAC7B,QAAQ,CAER;EACA,IAAI;GACA,eAAe,WAAW;EAC9B,QAAQ,CAER;EACA,KAAKD,oBAAoB,MAAM;CACnC;CAEA,qBAA2B;EACvB,MAAM,gBAAgB,KAAKC;EAC3B,KAAKA,iBAAiB;EAEtB,KAAK,MAAM,CAAC,SAAS,WAAW,KAAKL,aAAa;GAC9C,IAAI,KAAKC,aAAa,OAAO,MAAM,WAAW;GAC9C,KAAKD,YAAY,OAAO,OAAO;GAC/B,KAAKsB,sBAAsB,MAAM;EACrC;EACA,KAAK,MAAM,CAAC,SAAS,WAAW,KAAKL,mBAAmB;GACpD,IAAI,KAAKhB,aAAa,OAAO,MAAM,WAAW;GAC9C,KAAKgB,kBAAkB,OAAO,OAAO;GACrC,KAAKK,sBAAsB,MAAM;EACrC;EAEA,IAAI;GACA,eAAe,WAAW;EAC9B,QAAQ,CAER;CACJ;;;;CAKA,UAAa,SAAiB,UAA4C;EACtE,MAAM,SAAS,KAAKC,yBAAyB,OAAO;EACpD,OAAO;EAEP,MAAM,qBAAqB,SAAS;EACpC,MAAM,eAAe,SAAS;EAC9B,MAAM,oBAAoB,SAAS;EACnC,MAAM,sBAAsB,SAAS;EAErC,MAAM,UAAoC,gBACnC,QAAQ,KAAKJ,kBAAkB,cAAc,GAAG,IACjD,KAAA;EACN,MAAM,SAA6B,SAAS;GACxC,KAAKK,qBACD,SACA,6BACM,mBAAmB,IAAS,GAClC,OACJ;EACJ;EACA,IAAI,sBAAsB;EAC1B,MAAM,eAAe,qBACd,sBAA8B;GAC3B,IAAI,qBAAqB,qBAAqB;GAC9C,sBAAsB;GACtB,KAAKA,qBACD,SACA,sBACA,mBACA,OACJ;EACJ,IACA,KAAA;EACN,MAAM,iBAAiB,4BAEb,KAAKA,qBACD,SACA,wBACA,qBACA,OACJ,IACJ,KAAA;EAEN,OAAO,oBAAoB,IAAI,KAAK;EAEpC,IAAI,cAAc,OAAO,mBAAmB,IAAI,YAAY;EAC5D,IAAI,gBAAgB,OAAO,qBAAqB,IAAI,cAAc;EAClE,IAAI,SAAS,OAAO,cAAc,IAAI,OAAO;EAE7C,IAAI,SAAS;EACb,IAAI,gBAAgB,OAAO,KAAK,UAAU,cAAc;GACpD,MAAM,oBAAoB,OAAO;GACjC,qBAAqB;IACjB,IAAI,UAAU,OAAO,KAAK,UAAU,cAAc;IAClD,aAAa,iBAAiB;GAClC,CAAC;EACL;EAEA,aAAa;GACT,IAAI,QAAQ;GACZ,SAAS;GAET,OAAO,oBAAoB,OAAO,KAAK;GACvC,IAAI,cAAc,OAAO,mBAAmB,OAAO,YAAY;GAC/D,IAAI,gBAAgB,OAAO,qBAAqB,OAAO,cAAc;GACrE,IAAI,SAAS,OAAO,cAAc,OAAO,OAAO;GAEhD,OAAO;GACP,IAAI,OAAO,aAAa,GAAG;IAEvB,IADsB,KAAKxB,YAAY,IAAI,OAC3B,MAAM,QAAQ;IAE9B,KAAKA,YAAY,OAAO,OAAO;IAC/B,KAAKiB,kBAAkB,IAAI,SAAS,MAAM;IAE1C,qBAAqB;KACjB,IAAI,KAAKA,kBAAkB,IAAI,OAAO,MAAM,QAAQ;KACpD,KAAKA,kBAAkB,OAAO,OAAO;KAErC,KAAKK,sBAAsB,MAAM;KAEjC,IAAI,KAAKtB,YAAY,SAAS,KAAK,KAAKiB,kBAAkB,SAAS,GAC/D,KAAKQ,YAAY;IAEzB,CAAC;GACL;EACJ;CACJ;;;;CAKA,eAAsC,QAA6C;EAC/E,OAAO,KAAK,UAAsB,OAAO,SAAS;GAC9C,gBAAgB,SAAS;IACrB,IAAI;IACJ,IAAI;KACA,UAAU,WAAW,OAAO,QAAQ,IAAI;IAC5C,SAAS,OAAO;KACZ,KAAKN,kBACD,OAAO,SACP,kCAAkC,OAAO,SAAS,UAAU,KAAK,CACrE;KACA;IACJ;IACA,OAAO,cAAc,OAAO;GAChC;GACA,cAAc,OAAO;GACrB,gBAAgB,OAAO;GACvB,SAAS,OAAO;EACpB,CAAC;CACL;;;;CAKA,oBAA2C,QAA6C;EACpF,OAAO,KAAK,UAAwC,OAAO,SAAS;GAChE,gBAAgB,SAAS;IACrB,IAAI;IACJ,IAAI;KACA,MAAM,iBAAiB,OAAO,QAAQ,IAAI;IAC9C,SAAS,OAAO;KACZ,KAAKA,kBACD,OAAO,SACP,kCAAkC,OAAO,SAAS,UAAU,KAAK,CACrE;KACA;IACJ;IACA,IAAI,CAAC,KAAK;KACN,KAAKA,kBACD,OAAO,SACP,kCACI,OAAO,SACP,UACA,iCACJ,CACJ;KACA;IACJ;IACA,OAAO,cAAc,GAAG;GAC5B;GACA,cAAc,OAAO;GACrB,gBAAgB,OAAO;GACvB,SAAS,OAAO;EACpB,CAAC;CACL;;;;CAKA,aAAmB;EACf,KAAKM,YAAY;CACrB;;;;CAKA,oBAA0B;EACtB,KAAKC,mBAAmB;CAC5B;CAEA,IAAI,cAAuB;EACvB,OAAO,KAAKvB,kBAAkB,QAAQ,KAAKE,mBAAmB;CAClE;CAEA,IAAI,iBAAyB;EACzB,OAAO,KAAKL,YAAY;CAC5B;CAEA,IAAI,iBAAyB;EACzB,IAAI,QAAQ;EACZ,KAAK,MAAM,UAAU,KAAKA,YAAY,OAAO,GACzC,SAAS,OAAO;EAEpB,OAAO;CACX;AACJ"}

package/dist/realtime/index.d.ts

@@ -0,0 +1,3 @@
+import { ConnectChannelParams, PolyesterRealtime, SubscribeHandlers } from "./types.js";
+import { RealtimeConfig } from "./client.js";
+export type { ConnectChannelParams, PolyesterRealtime, RealtimeConfig, SubscribeHandlers };

package/dist/realtime/snapshot-then-stream.js

@@ -0,0 +1,144 @@
+import { createSdkSubscriptionErrorContext } from "../shared/subscription-errors.js";
+import { isDev } from "../utils/is-dev.js";
+import { formatConnectError } from "../utils/errors.js";
+//#region src/realtime/snapshot-then-stream.ts
+/**
+* Snapshot-then-stream for feed state. By default, the buffer caps at
+* `maxBufferedPublications` and drops the OLDEST publications, which is correct for
+* ephemeral feeds where a later publication supersedes earlier ones. Keyed state can
+* provide `bufferPublicationKey` to retain the latest value for every key without FIFO
+* loss. Entity transitions (orders, triggers, balances, trades) must NOT use this —
+* their ordering contract lives in the app-side `EntityStreamStore`, which buffers
+* unbounded and replays because dropping an event loses a row transition.
+*/
+function snapshotThenStream(params) {
+	const maxBufferedPublications = params.maxBufferedPublications ?? 200;
+	let droppedPublications = 0;
+	let ready = false;
+	let disposed = false;
+	let refreshGeneration = 0;
+	let pendingPublications = [];
+	let retryAttempts = 0;
+	let retryTimer = null;
+	function reportSnapshotError(error) {
+		if (isDev() && params.snapshotErrorLog) console.error(params.snapshotErrorLog, error);
+		params.onError?.(createSdkSubscriptionErrorContext(params.channel, "snapshot", formatConnectError(error, "snapshot failed")));
+	}
+	function takePendingPublications() {
+		const buffered = pendingPublications;
+		pendingPublications = [];
+		return buffered;
+	}
+	function applyBufferedAsLive() {
+		const buffered = takePendingPublications();
+		if (buffered.length === 0) return;
+		params.applyLivePublications(buffered);
+	}
+	function bufferPublications(publications) {
+		if (params.bufferPublicationKey) {
+			const byKey = /* @__PURE__ */ new Map();
+			for (const publication of pendingPublications) byKey.set(params.bufferPublicationKey(publication), publication);
+			for (const publication of publications) byKey.set(params.bufferPublicationKey(publication), publication);
+			pendingPublications = Array.from(byKey.values());
+			return;
+		}
+		const next = pendingPublications.concat(publications);
+		if (next.length > maxBufferedPublications) {
+			droppedPublications += next.length - maxBufferedPublications;
+			if (isDev()) console.warn(`[snapshot-then-stream] ${params.channel}: buffer cap dropped ${droppedPublications} publication(s) while snapshot in flight`);
+		}
+		pendingPublications = next.slice(-maxBufferedPublications);
+	}
+	function clearRetryTimer() {
+		if (retryTimer === null) return;
+		clearTimeout(retryTimer);
+		retryTimer = null;
+	}
+	function reportBufferedPublicationError(error) {
+		params.onError?.(createSdkSubscriptionErrorContext(params.channel, "publication_handler", error));
+	}
+	function scheduleSnapshotRetry() {
+		const retry = params.snapshotRetry;
+		if (!retry || retryAttempts >= retry.maxAttempts || disposed) return;
+		const delayMs = retry.delayMs * 2 ** retryAttempts;
+		retryAttempts++;
+		retryTimer = setTimeout(() => {
+			retryTimer = null;
+			refreshSnapshot(false);
+		}, delayMs);
+	}
+	function refreshSnapshot(resetRetries = true) {
+		if (disposed) return;
+		clearRetryTimer();
+		if (resetRetries) retryAttempts = 0;
+		const generation = ++refreshGeneration;
+		ready = false;
+		Promise.resolve().then(() => params.fetchSnapshot()).then((snapshot) => {
+			if (disposed || generation !== refreshGeneration) return;
+			const buffered = takePendingPublications();
+			params.applySnapshot(snapshot, buffered);
+			if (disposed || generation !== refreshGeneration) return;
+			ready = true;
+			retryAttempts = 0;
+		}).catch((error) => {
+			if (disposed || generation !== refreshGeneration) return;
+			reportSnapshotError(error);
+			if (params.snapshotFailureMode === "live") {
+				ready = true;
+				try {
+					applyBufferedAsLive();
+				} catch (publicationError) {
+					reportBufferedPublicationError(publicationError);
+				}
+			}
+			scheduleSnapshotRetry();
+		});
+	}
+	const unsubscribeRealtime = params.realtime.connectProtoChannel({
+		channel: params.channel,
+		schema: params.schema,
+		onPublication: (message) => {
+			const publications = params.readPublication(message);
+			if (publications.length === 0) return;
+			if (!ready) {
+				bufferPublications(publications);
+				return;
+			}
+			params.applyLivePublications(publications);
+		},
+		onConnected: () => {
+			if (disposed) return;
+			pendingPublications = [];
+			refreshSnapshot();
+			params.onOpen?.();
+		},
+		onDisconnected: () => {
+			if (disposed) return;
+			clearRetryTimer();
+			refreshGeneration++;
+			ready = false;
+			pendingPublications = [];
+			params.onClose?.();
+		},
+		onError: (ctx) => params.onError?.(ctx)
+	});
+	function unsubscribe() {
+		disposed = true;
+		clearRetryTimer();
+		refreshGeneration++;
+		pendingPublications = [];
+		try {
+			unsubscribeRealtime();
+		} catch {}
+	}
+	return {
+		unsubscribe,
+		refreshSnapshot,
+		isReady: () => ready,
+		isDisposed: () => disposed
+	};
+}
+//#endregion
+export { snapshotThenStream };
+
+//# sourceMappingURL=snapshot-then-stream.js.map

package/dist/realtime/snapshot-then-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-then-stream.js","names":[],"sources":["../../src/realtime/snapshot-then-stream.ts"],"sourcesContent":["import type { DescMessage, MessageShape } from \"@bufbuild/protobuf\";\nimport {\n    createSdkSubscriptionErrorContext,\n    type SdkSubscriptionErrorContext,\n} from \"../shared/subscription-errors.js\";\nimport type { PolyesterRealtime } from \"./types.js\";\nimport { formatConnectError } from \"../utils/errors.js\";\nimport { isDev } from \"../utils/is-dev.js\";\n\nexport interface SnapshotThenStreamSubscription {\n    unsubscribe: () => void;\n    refreshSnapshot: () => void;\n    isReady: () => boolean;\n    isDisposed: () => boolean;\n}\n\nexport interface SnapshotThenStreamInput<TSchema extends DescMessage, TSnapshot, TPublication> {\n    realtime: PolyesterRealtime;\n    channel: string;\n    schema: TSchema;\n    maxBufferedPublications?: number;\n    bufferPublicationKey?: (publication: TPublication) => PropertyKey;\n    snapshotRetry?: {\n        maxAttempts: number;\n        delayMs: number;\n    };\n    snapshotFailureMode?: \"wait\" | \"live\";\n    snapshotErrorLog?: string;\n    fetchSnapshot: () => Promise<TSnapshot>;\n    readPublication: (message: MessageShape<TSchema>) => readonly TPublication[];\n    applySnapshot: (snapshot: TSnapshot, bufferedPublications: readonly TPublication[]) => void;\n    applyLivePublications: (publications: readonly TPublication[]) => void;\n    onOpen?: () => void;\n    onClose?: () => void;\n    onError?: (ctx: SdkSubscriptionErrorContext) => void;\n}\n\n/**\n * Snapshot-then-stream for feed state. By default, the buffer caps at\n * `maxBufferedPublications` and drops the OLDEST publications, which is correct for\n * ephemeral feeds where a later publication supersedes earlier ones. Keyed state can\n * provide `bufferPublicationKey` to retain the latest value for every key without FIFO\n * loss. Entity transitions (orders, triggers, balances, trades) must NOT use this —\n * their ordering contract lives in the app-side `EntityStreamStore`, which buffers\n * unbounded and replays because dropping an event loses a row transition.\n */\nexport function snapshotThenStream<TSchema extends DescMessage, TSnapshot, TPublication>(\n    params: SnapshotThenStreamInput<TSchema, TSnapshot, TPublication>,\n): SnapshotThenStreamSubscription {\n    const maxBufferedPublications = params.maxBufferedPublications ?? 200;\n    let droppedPublications = 0;\n\n    let ready = false;\n    let disposed = false;\n    let refreshGeneration = 0;\n    let pendingPublications: TPublication[] = [];\n    let retryAttempts = 0;\n    let retryTimer: ReturnType<typeof setTimeout> | null = null;\n\n    function reportSnapshotError(error: unknown): void {\n        if (isDev() && params.snapshotErrorLog) {\n            console.error(params.snapshotErrorLog, error);\n        }\n        params.onError?.(\n            createSdkSubscriptionErrorContext(\n                params.channel,\n                \"snapshot\",\n                formatConnectError(error, \"snapshot failed\"),\n            ),\n        );\n    }\n\n    function takePendingPublications(): TPublication[] {\n        const buffered = pendingPublications;\n        pendingPublications = [];\n        return buffered;\n    }\n\n    function applyBufferedAsLive(): void {\n        const buffered = takePendingPublications();\n        if (buffered.length === 0) return;\n        params.applyLivePublications(buffered);\n    }\n\n    function bufferPublications(publications: readonly TPublication[]): void {\n        if (params.bufferPublicationKey) {\n            const byKey = new Map<PropertyKey, TPublication>();\n            for (const publication of pendingPublications) {\n                byKey.set(params.bufferPublicationKey(publication), publication);\n            }\n            for (const publication of publications) {\n                byKey.set(params.bufferPublicationKey(publication), publication);\n            }\n            pendingPublications = Array.from(byKey.values());\n            return;\n        }\n\n        const next = pendingPublications.concat(publications);\n        if (next.length > maxBufferedPublications) {\n            droppedPublications += next.length - maxBufferedPublications;\n            if (isDev()) {\n                console.warn(\n                    `[snapshot-then-stream] ${params.channel}: buffer cap dropped ${droppedPublications} publication(s) while snapshot in flight`,\n                );\n            }\n        }\n        pendingPublications = next.slice(-maxBufferedPublications);\n    }\n\n    function clearRetryTimer(): void {\n        if (retryTimer === null) return;\n        clearTimeout(retryTimer);\n        retryTimer = null;\n    }\n\n    function reportBufferedPublicationError(error: unknown): void {\n        params.onError?.(\n            createSdkSubscriptionErrorContext(params.channel, \"publication_handler\", error),\n        );\n    }\n\n    function scheduleSnapshotRetry(): void {\n        const retry = params.snapshotRetry;\n        if (!retry || retryAttempts >= retry.maxAttempts || disposed) return;\n\n        const delayMs = retry.delayMs * 2 ** retryAttempts;\n        retryAttempts++;\n        retryTimer = setTimeout(() => {\n            retryTimer = null;\n            refreshSnapshot(false);\n        }, delayMs);\n    }\n\n    function refreshSnapshot(resetRetries = true): void {\n        if (disposed) return;\n        clearRetryTimer();\n        if (resetRetries) retryAttempts = 0;\n\n        const generation = ++refreshGeneration;\n        ready = false;\n\n        Promise.resolve()\n            .then(() => params.fetchSnapshot())\n            .then((snapshot) => {\n                if (disposed || generation !== refreshGeneration) return;\n\n                const buffered = takePendingPublications();\n                params.applySnapshot(snapshot, buffered);\n\n                if (disposed || generation !== refreshGeneration) return;\n                ready = true;\n                retryAttempts = 0;\n            })\n            .catch((error: unknown) => {\n                if (disposed || generation !== refreshGeneration) return;\n                reportSnapshotError(error);\n                if (params.snapshotFailureMode === \"live\") {\n                    ready = true;\n                    try {\n                        applyBufferedAsLive();\n                    } catch (publicationError) {\n                        reportBufferedPublicationError(publicationError);\n                    }\n                }\n                scheduleSnapshotRetry();\n            });\n    }\n\n    const unsubscribeRealtime = params.realtime.connectProtoChannel({\n        channel: params.channel,\n        schema: params.schema,\n        onPublication: (message) => {\n            const publications = params.readPublication(message);\n            if (publications.length === 0) return;\n\n            if (!ready) {\n                bufferPublications(publications);\n                return;\n            }\n\n            params.applyLivePublications(publications);\n        },\n        onConnected: () => {\n            if (disposed) return;\n            pendingPublications = [];\n            refreshSnapshot();\n            params.onOpen?.();\n        },\n        onDisconnected: () => {\n            if (disposed) return;\n            clearRetryTimer();\n            refreshGeneration++;\n            ready = false;\n            pendingPublications = [];\n            params.onClose?.();\n        },\n        onError: (ctx) => params.onError?.(ctx),\n    });\n\n    function unsubscribe(): void {\n        disposed = true;\n        clearRetryTimer();\n        refreshGeneration++;\n        pendingPublications = [];\n        try {\n            unsubscribeRealtime();\n        } catch {\n            // noop\n        }\n    }\n\n    return {\n        unsubscribe,\n        refreshSnapshot,\n        isReady: () => ready,\n        isDisposed: () => disposed,\n    };\n}\n"],"mappings":"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"}

package/dist/realtime/types.d.ts

@@ -0,0 +1,41 @@
+import { SdkSubscriptionErrorContext } from "../shared/subscription-errors.js";
+import { DescMessage, MessageShape } from "@bufbuild/protobuf";
+//#region src/realtime/types.d.ts
+interface SubscribeHandlers<T> {
+  onPublication: (data: T) => void;
+  onSubscribed?: () => void;
+  onUnsubscribed?: () => void;
+  onError?: (ctx: SdkSubscriptionErrorContext) => void;
+}
+interface ConnectChannelParams<T extends DescMessage> {
+  channel: string;
+  schema: T;
+  onPublication: (data: MessageShape<T>) => void;
+  onConnected?: () => void;
+  onDisconnected?: () => void;
+  onError?: (ctx: SdkSubscriptionErrorContext) => void;
+}
+/**
+ * Structural realtime contract consumed by SDK services. The default
+ * implementation is the Centrifuge-backed {@link ../realtime/client.js RealtimeClient};
+ * alternative implementations (in-memory mocks, custom stacks) can be injected
+ * via the client config's `realtimeClient` field.
+ */
+interface PolyesterRealtime {
+  /** Subscribes to a realtime channel and returns an unsubscribe function. */
+  subscribe<T>(channel: string, handlers: SubscribeHandlers<T>): () => void;
+  /** Connects to a realtime channel with a custom message decoder. */
+  connectChannel<T extends DescMessage>(params: ConnectChannelParams<T>): () => void;
+  /** Connects to a realtime channel that emits protobuf messages. */
+  connectProtoChannel<T extends DescMessage>(params: ConnectChannelParams<T>): () => void;
+  /** Disconnects from all active channels. */
+  disconnect(): void;
+  /** Disconnects authenticated realtime state without touching public channels. */
+  disconnectPrivate(): void;
+  readonly isConnected: boolean;
+  readonly activeChannels: number;
+  readonly totalConsumers: number;
+}
+//#endregion
+export { ConnectChannelParams, PolyesterRealtime, SubscribeHandlers };
+//# sourceMappingURL=types.d.ts.map

package/dist/realtime/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/realtime/types.ts"],"mappings":";;;UAGiB,kBAAkB;EAC/B,gBAAgB,MAAM;EACtB;EACA;EACA,WAAW,KAAK;;UAGH,qBAAqB,UAAU;EAC5C;EACA,QAAQ;EACR,gBAAgB,MAAM,aAAa;EACnC;EACA;EACA,WAAW,KAAK;;;;;;;;UASH;;EAEb,UAAU,GAAG,iBAAiB,UAAU,kBAAkB;;EAE1D,eAAe,UAAU,aAAa,QAAQ,qBAAqB;;EAEnE,oBAAoB,UAAU,aAAa,QAAQ,qBAAqB;;EAExE;;EAEA;WACS;WACA;WACA"}

package/dist/server-client.d.ts

@@ -0,0 +1,73 @@
+import "./environment.js";
+import { ApiKeyEd25519AuthProvider, JwtAuthProvider } from "./shared/transports.js";
+import { SubaccountResolver } from "./services/subaccount-resolver.js";
+import { Me } from "./services/auth/auth.js";
+import { PolyesterClient, PolyesterClientBaseConfig } from "./core-client.js";
+import { CookieGetter } from "./utils/cookies.js";
+import { ServerSessionSnapshot } from "./services/auth/session.types.js";
+import { POLYESTER_AUTH_TOKEN_COOKIE_NAME, POLYESTER_SESSION_COOKIE_NAME } from "./services/auth/cookie-constants.js";
+//#region src/server-client.d.ts
+interface PolyesterServerClientConfig extends PolyesterClientBaseConfig {
+  /** Auth provider config for HTTP/Connect endpoints. */
+  auth?: JwtAuthProvider | ApiKeyEd25519AuthProvider;
+  /** Display-only session data parsed from cookies. Not proof of authentication. */
+  session?: ServerSessionSnapshot;
+  /**
+   * Use unsigned display-session `activeAccount` as the default subaccount for
+   * calls that omit `subaccountId`. This preserves account-switcher intent for
+   * apps that explicitly opt in; backend authorization must still decide what
+   * the authenticated user can access.
+   */
+  useDisplaySessionActiveAccountAsDefault?: boolean;
+}
+/**
+ * Server-side SDK client that can parse display-session cookies and verify bearer-token sessions with the backend.
+ */
+declare class PolyesterServerClient extends PolyesterClient {
+  #private;
+  constructor(config: PolyesterServerClientConfig);
+  /**
+   * Creates a resolver for server-side subaccount defaults. Display-session
+   * `activeAccount` is only used as caller intent when explicitly enabled;
+   * backend auth remains authoritative.
+   */
+  protected createSubaccountResolver(): SubaccountResolver;
+  get hasAuthProvider(): boolean;
+  get hasBearerToken(): boolean;
+  get hasUsableBearerToken(): boolean;
+  get hasDisplaySession(): boolean;
+  get session(): ServerSessionSnapshot;
+  /**
+   * Verifies the current server session and returns its auth state.
+   */
+  verifySession(): Promise<Me | null>;
+}
+interface CreateServerClientFromCookiesParams extends Pick<PolyesterClientBaseConfig, "environment" | "interceptors" | "realtime" | "wireFormat" | "catalog" | "catalogSnapshot" | "catalogCell" | "transports" | "realtimeClient"> {
+  cookies: CookieGetter;
+  /**
+   * Use unsigned display-session `activeAccount` as the default subaccount for
+   * calls that omit `subaccountId`. This is caller intent from UI hydration,
+   * not proof of authority; backend authorization remains authoritative.
+   */
+  useDisplaySessionActiveAccountAsDefault?: boolean;
+}
+interface CreateServerClientFromRequestParams extends Pick<PolyesterClientBaseConfig, "environment" | "interceptors" | "realtime" | "wireFormat" | "catalog" | "catalogSnapshot" | "catalogCell" | "transports" | "realtimeClient"> {
+  request: Request;
+  /**
+   * Use unsigned display-session `activeAccount` as the default subaccount for
+   * calls that omit `subaccountId`. This is caller intent from UI hydration,
+   * not proof of authority; backend authorization remains authoritative.
+   */
+  useDisplaySessionActiveAccountAsDefault?: boolean;
+}
+/**
+ * Creates a server SDK client from a cookie source.
+ */
+declare function createPolyesterServerClientFromCookies(params: CreateServerClientFromCookiesParams): PolyesterServerClient;
+/**
+ * Creates a server SDK client from a Request object.
+ */
+declare function createPolyesterServerClientFromRequest(params: CreateServerClientFromRequestParams): PolyesterServerClient;
+//#endregion
+export { CreateServerClientFromCookiesParams, CreateServerClientFromRequestParams, PolyesterServerClient, PolyesterServerClientConfig, type ServerSessionSnapshot, createPolyesterServerClientFromCookies, createPolyesterServerClientFromRequest };
+//# sourceMappingURL=server-client.d.ts.map

package/dist/server-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-client.d.ts","names":[],"sources":["../src/server-client.ts"],"mappings":";;;;;;;;;UA0BiB,oCAAoC;;EAEjD,OAAO,kBAAkB;;EAEzB,UAAU;;;;;;;EAOV;;;;;cAMS,8BAA8B;;EAK3B,YAAA,QAAQ;;;;;;YA0BD,4BAA4B;MAc3C;MAIA;MAIA;MAIA;MAIA,WAAW;;;;EAOT,iBAAiB,QAAQ;;UAWlB,4CAA4C,KACzD;EAWA,SAAS;;;;;;EAMT;;UAGa,4CAA4C,KACzD;EAWA,SAAS;;;;;;EAMT;;;;;iBAMY,uCACZ,QAAQ,sCACT;;;;iBA4Ba,uCACZ,QAAQ,sCACT"}

package/dist/server-client.js

@@ -0,0 +1,126 @@
+import { PolyesterClient } from "./core-client.js";
+import "./services/auth/cookie-constants.js";
+import { emptyServerSessionSnapshot, parseServerSessionSnapshot } from "./services/auth/session.js";
+import { isJwtValid } from "./utils/jwt.js";
+//#region src/server-client.ts
+/**
+* Parses a serialized session cookie into SDK session data.
+*/
+function parseSessionCookie(cookies, environment) {
+	return parseServerSessionSnapshot(cookies, environment);
+}
+/**
+* Server-side SDK client that can parse display-session cookies and verify bearer-token sessions with the backend.
+*/
+var PolyesterServerClient = class extends PolyesterClient {
+	#hasAuthProvider;
+	#session;
+	#useDisplaySessionActiveAccountAsDefault;
+	constructor(config) {
+		const auth = config.auth ?? void 0;
+		super({
+			environment: config.environment,
+			interceptors: config.interceptors,
+			auth,
+			wireFormat: config.wireFormat,
+			realtime: config.realtime,
+			catalog: config.catalog,
+			catalogSnapshot: config.catalogSnapshot,
+			catalogCell: config.catalogCell,
+			transports: config.transports,
+			realtimeClient: config.realtimeClient
+		});
+		this.#hasAuthProvider = !!auth;
+		this.#session = config.session ?? emptyServerSessionSnapshot();
+		this.#useDisplaySessionActiveAccountAsDefault = config.useDisplaySessionActiveAccountAsDefault ?? false;
+	}
+	/**
+	* Creates a resolver for server-side subaccount defaults. Display-session
+	* `activeAccount` is only used as caller intent when explicitly enabled;
+	* backend auth remains authoritative.
+	*/
+	createSubaccountResolver() {
+		return {
+			getDefaultSubaccountId: () => {
+				if (!this.#useDisplaySessionActiveAccountAsDefault) return null;
+				const activeAccount = this.#session.activeAccount;
+				if (activeAccount && !activeAccount.isMain) return activeAccount.accountId;
+				return null;
+			},
+			getActiveAccountId: () => this.#session.activeAccount?.accountId ?? null,
+			getMainAccountId: () => this.#session.activeAccount?.mainAccountId ?? null
+		};
+	}
+	get hasAuthProvider() {
+		return this.#hasAuthProvider;
+	}
+	get hasBearerToken() {
+		return !!this.#session.bearerToken;
+	}
+	get hasUsableBearerToken() {
+		return isJwtValid(this.#session.bearerToken);
+	}
+	get hasDisplaySession() {
+		return this.#session.hasDisplaySession;
+	}
+	get session() {
+		return this.#session;
+	}
+	/**
+	* Verifies the current server session and returns its auth state.
+	*/
+	async verifySession() {
+		if (!this.#hasAuthProvider) return null;
+		try {
+			return await this.auth.me();
+		} catch {
+			return null;
+		}
+	}
+};
+/**
+* Creates a server SDK client from a cookie source.
+*/
+function createPolyesterServerClientFromCookies(params) {
+	const session = parseSessionCookie(params.cookies, params.environment);
+	const auth = isJwtValid(session.bearerToken) ? {
+		kind: "jwt",
+		getToken: () => session.bearerToken
+	} : void 0;
+	return new PolyesterServerClient({
+		environment: params.environment,
+		interceptors: params.interceptors,
+		session,
+		wireFormat: params.wireFormat,
+		realtime: params.realtime,
+		catalog: params.catalog,
+		catalogSnapshot: params.catalogSnapshot,
+		catalogCell: params.catalogCell,
+		transports: params.transports,
+		realtimeClient: params.realtimeClient,
+		auth,
+		useDisplaySessionActiveAccountAsDefault: params.useDisplaySessionActiveAccountAsDefault
+	});
+}
+/**
+* Creates a server SDK client from a Request object.
+*/
+function createPolyesterServerClientFromRequest(params) {
+	return createPolyesterServerClientFromCookies({
+		cookies: params.request,
+		environment: params.environment,
+		interceptors: params.interceptors,
+		wireFormat: params.wireFormat,
+		realtime: params.realtime,
+		catalog: params.catalog,
+		catalogSnapshot: params.catalogSnapshot,
+		catalogCell: params.catalogCell,
+		transports: params.transports,
+		realtimeClient: params.realtimeClient,
+		useDisplaySessionActiveAccountAsDefault: params.useDisplaySessionActiveAccountAsDefault
+	});
+}
+//#endregion
+export { PolyesterServerClient, createPolyesterServerClientFromCookies, createPolyesterServerClientFromRequest, parseSessionCookie };
+
+//# sourceMappingURL=server-client.js.map

package/dist/server-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-client.js","names":["#hasAuthProvider","#session","#useDisplaySessionActiveAccountAsDefault"],"sources":["../src/server-client.ts"],"sourcesContent":["import { PolyesterClient, type PolyesterClientBaseConfig } from \"./core-client.js\";\nimport {\n    POLYESTER_AUTH_TOKEN_COOKIE_NAME,\n    POLYESTER_SESSION_COOKIE_NAME,\n} from \"./services/auth/cookie-constants.js\";\nimport type { ServerSessionSnapshot } from \"./services/auth/session.types.js\";\nimport { emptyServerSessionSnapshot, parseServerSessionSnapshot } from \"./services/auth/session.js\";\nimport type { CookieGetter } from \"./utils/cookies.js\";\nimport type { JwtAuthProvider, ApiKeyEd25519AuthProvider } from \"./shared/transports.js\";\nimport type { SubaccountResolver } from \"./services/subaccount-resolver.js\";\nimport { isJwtValid } from \"./utils/jwt.js\";\nimport type { Me } from \"./services/auth/auth.js\";\nimport type { PolyesterEnvironment } from \"./environment.js\";\n\nexport type { ServerSessionSnapshot };\n\n/**\n * Parses a serialized session cookie into SDK session data.\n */\nexport function parseSessionCookie(\n    cookies: CookieGetter,\n    environment: PolyesterEnvironment,\n): ServerSessionSnapshot {\n    return parseServerSessionSnapshot(cookies, environment);\n}\n\nexport interface PolyesterServerClientConfig extends PolyesterClientBaseConfig {\n    /** Auth provider config for HTTP/Connect endpoints. */\n    auth?: JwtAuthProvider | ApiKeyEd25519AuthProvider;\n    /** Display-only session data parsed from cookies. Not proof of authentication. */\n    session?: ServerSessionSnapshot;\n    /**\n     * Use unsigned display-session `activeAccount` as the default subaccount for\n     * calls that omit `subaccountId`. This preserves account-switcher intent for\n     * apps that explicitly opt in; backend authorization must still decide what\n     * the authenticated user can access.\n     */\n    useDisplaySessionActiveAccountAsDefault?: boolean;\n}\n\n/**\n * Server-side SDK client that can parse display-session cookies and verify bearer-token sessions with the backend.\n */\nexport class PolyesterServerClient extends PolyesterClient {\n    #hasAuthProvider: boolean;\n    #session: ServerSessionSnapshot;\n    #useDisplaySessionActiveAccountAsDefault: boolean;\n\n    constructor(config: PolyesterServerClientConfig) {\n        const auth = config.auth ?? undefined;\n\n        super({\n            environment: config.environment,\n            interceptors: config.interceptors,\n            auth,\n            wireFormat: config.wireFormat,\n            realtime: config.realtime,\n            catalog: config.catalog,\n            catalogSnapshot: config.catalogSnapshot,\n            catalogCell: config.catalogCell,\n            transports: config.transports,\n            realtimeClient: config.realtimeClient,\n        });\n        this.#hasAuthProvider = !!auth;\n        this.#session = config.session ?? emptyServerSessionSnapshot();\n        this.#useDisplaySessionActiveAccountAsDefault =\n            config.useDisplaySessionActiveAccountAsDefault ?? false;\n    }\n\n    /**\n     * Creates a resolver for server-side subaccount defaults. Display-session\n     * `activeAccount` is only used as caller intent when explicitly enabled;\n     * backend auth remains authoritative.\n     */\n    protected override createSubaccountResolver(): SubaccountResolver {\n        return {\n            getDefaultSubaccountId: () => {\n                if (!this.#useDisplaySessionActiveAccountAsDefault) return null;\n\n                const activeAccount = this.#session.activeAccount;\n                if (activeAccount && !activeAccount.isMain) return activeAccount.accountId;\n                return null;\n            },\n            getActiveAccountId: () => this.#session.activeAccount?.accountId ?? null,\n            getMainAccountId: () => this.#session.activeAccount?.mainAccountId ?? null,\n        };\n    }\n\n    get hasAuthProvider(): boolean {\n        return this.#hasAuthProvider;\n    }\n\n    get hasBearerToken(): boolean {\n        return !!this.#session.bearerToken;\n    }\n\n    get hasUsableBearerToken(): boolean {\n        return isJwtValid(this.#session.bearerToken);\n    }\n\n    get hasDisplaySession(): boolean {\n        return this.#session.hasDisplaySession;\n    }\n\n    get session(): ServerSessionSnapshot {\n        return this.#session;\n    }\n\n    /**\n     * Verifies the current server session and returns its auth state.\n     */\n    async verifySession(): Promise<Me | null> {\n        if (!this.#hasAuthProvider) return null;\n\n        try {\n            return await this.auth.me();\n        } catch {\n            return null;\n        }\n    }\n}\n\nexport interface CreateServerClientFromCookiesParams extends Pick<\n    PolyesterClientBaseConfig,\n    | \"environment\"\n    | \"interceptors\"\n    | \"realtime\"\n    | \"wireFormat\"\n    | \"catalog\"\n    | \"catalogSnapshot\"\n    | \"catalogCell\"\n    | \"transports\"\n    | \"realtimeClient\"\n> {\n    cookies: CookieGetter;\n    /**\n     * Use unsigned display-session `activeAccount` as the default subaccount for\n     * calls that omit `subaccountId`. This is caller intent from UI hydration,\n     * not proof of authority; backend authorization remains authoritative.\n     */\n    useDisplaySessionActiveAccountAsDefault?: boolean;\n}\n\nexport interface CreateServerClientFromRequestParams extends Pick<\n    PolyesterClientBaseConfig,\n    | \"environment\"\n    | \"interceptors\"\n    | \"realtime\"\n    | \"wireFormat\"\n    | \"catalog\"\n    | \"catalogSnapshot\"\n    | \"catalogCell\"\n    | \"transports\"\n    | \"realtimeClient\"\n> {\n    request: Request;\n    /**\n     * Use unsigned display-session `activeAccount` as the default subaccount for\n     * calls that omit `subaccountId`. This is caller intent from UI hydration,\n     * not proof of authority; backend authorization remains authoritative.\n     */\n    useDisplaySessionActiveAccountAsDefault?: boolean;\n}\n\n/**\n * Creates a server SDK client from a cookie source.\n */\nexport function createPolyesterServerClientFromCookies(\n    params: CreateServerClientFromCookiesParams,\n): PolyesterServerClient {\n    const session = parseSessionCookie(params.cookies, params.environment);\n    const auth = isJwtValid(session.bearerToken)\n        ? ({\n              kind: \"jwt\",\n              getToken: () => session.bearerToken,\n          } satisfies JwtAuthProvider)\n        : undefined;\n\n    return new PolyesterServerClient({\n        environment: params.environment,\n        interceptors: params.interceptors,\n        session,\n        wireFormat: params.wireFormat,\n        realtime: params.realtime,\n        catalog: params.catalog,\n        catalogSnapshot: params.catalogSnapshot,\n        catalogCell: params.catalogCell,\n        transports: params.transports,\n        realtimeClient: params.realtimeClient,\n        auth,\n        useDisplaySessionActiveAccountAsDefault: params.useDisplaySessionActiveAccountAsDefault,\n    });\n}\n\n/**\n * Creates a server SDK client from a Request object.\n */\nexport function createPolyesterServerClientFromRequest(\n    params: CreateServerClientFromRequestParams,\n): PolyesterServerClient {\n    return createPolyesterServerClientFromCookies({\n        cookies: params.request,\n        environment: params.environment,\n        interceptors: params.interceptors,\n        wireFormat: params.wireFormat,\n        realtime: params.realtime,\n        catalog: params.catalog,\n        catalogSnapshot: params.catalogSnapshot,\n        catalogCell: params.catalogCell,\n        transports: params.transports,\n        realtimeClient: params.realtimeClient,\n        useDisplaySessionActiveAccountAsDefault: params.useDisplaySessionActiveAccountAsDefault,\n    });\n}\n\n/**\n * Reads a bearer token from supported auth cookies.\n */\nexport function getBearerTokenFromCookies(\n    cookies: CookieGetter,\n    environment: PolyesterEnvironment,\n): string | null {\n    return parseSessionCookie(cookies, environment).bearerToken;\n}\n\nexport { POLYESTER_AUTH_TOKEN_COOKIE_NAME, POLYESTER_SESSION_COOKIE_NAME };\n"],"mappings":";;;;;;;;AAmBA,SAAgB,mBACZ,SACA,aACqB;CACrB,OAAO,2BAA2B,SAAS,WAAW;AAC1D;;;;AAmBA,IAAa,wBAAb,cAA2C,gBAAgB;CACvD;CACA;CACA;CAEA,YAAY,QAAqC;EAC7C,MAAM,OAAO,OAAO,QAAQ,KAAA;EAE5B,MAAM;GACF,aAAa,OAAO;GACpB,cAAc,OAAO;GACrB;GACA,YAAY,OAAO;GACnB,UAAU,OAAO;GACjB,SAAS,OAAO;GAChB,iBAAiB,OAAO;GACxB,aAAa,OAAO;GACpB,YAAY,OAAO;GACnB,gBAAgB,OAAO;EAC3B,CAAC;EACD,KAAKA,mBAAmB,CAAC,CAAC;EAC1B,KAAKC,WAAW,OAAO,WAAW,2BAA2B;EAC7D,KAAKC,2CACD,OAAO,2CAA2C;CAC1D;;;;;;CAOA,2BAAkE;EAC9D,OAAO;GACH,8BAA8B;IAC1B,IAAI,CAAC,KAAKA,0CAA0C,OAAO;IAE3D,MAAM,gBAAgB,KAAKD,SAAS;IACpC,IAAI,iBAAiB,CAAC,cAAc,QAAQ,OAAO,cAAc;IACjE,OAAO;GACX;GACA,0BAA0B,KAAKA,SAAS,eAAe,aAAa;GACpE,wBAAwB,KAAKA,SAAS,eAAe,iBAAiB;EAC1E;CACJ;CAEA,IAAI,kBAA2B;EAC3B,OAAO,KAAKD;CAChB;CAEA,IAAI,iBAA0B;EAC1B,OAAO,CAAC,CAAC,KAAKC,SAAS;CAC3B;CAEA,IAAI,uBAAgC;EAChC,OAAO,WAAW,KAAKA,SAAS,WAAW;CAC/C;CAEA,IAAI,oBAA6B;EAC7B,OAAO,KAAKA,SAAS;CACzB;CAEA,IAAI,UAAiC;EACjC,OAAO,KAAKA;CAChB;;;;CAKA,MAAM,gBAAoC;EACtC,IAAI,CAAC,KAAKD,kBAAkB,OAAO;EAEnC,IAAI;GACA,OAAO,MAAM,KAAK,KAAK,GAAG;EAC9B,QAAQ;GACJ,OAAO;EACX;CACJ;AACJ;;;;AA+CA,SAAgB,uCACZ,QACqB;CACrB,MAAM,UAAU,mBAAmB,OAAO,SAAS,OAAO,WAAW;CACrE,MAAM,OAAO,WAAW,QAAQ,WAAW,IACpC;EACG,MAAM;EACN,gBAAgB,QAAQ;CAC5B,IACA,KAAA;CAEN,OAAO,IAAI,sBAAsB;EAC7B,aAAa,OAAO;EACpB,cAAc,OAAO;EACrB;EACA,YAAY,OAAO;EACnB,UAAU,OAAO;EACjB,SAAS,OAAO;EAChB,iBAAiB,OAAO;EACxB,aAAa,OAAO;EACpB,YAAY,OAAO;EACnB,gBAAgB,OAAO;EACvB;EACA,yCAAyC,OAAO;CACpD,CAAC;AACL;;;;AAKA,SAAgB,uCACZ,QACqB;CACrB,OAAO,uCAAuC;EAC1C,SAAS,OAAO;EAChB,aAAa,OAAO;EACpB,cAAc,OAAO;EACrB,YAAY,OAAO;EACnB,UAAU,OAAO;EACjB,SAAS,OAAO;EAChB,iBAAiB,OAAO;EACxB,aAAa,OAAO;EACpB,YAAY,OAAO;EACnB,gBAAgB,OAAO;EACvB,yCAAyC,OAAO;CACpD,CAAC;AACL"}

package/dist/server-session.d.ts

@@ -0,0 +1,4 @@
+import { ServerSessionSnapshot } from "./services/auth/session.types.js";
+import { emptyServerSessionSnapshot, parseServerSessionSnapshot } from "./services/auth/session.js";
+import { isJwtValid } from "./utils/jwt.js";
+export { type ServerSessionSnapshot, emptyServerSessionSnapshot, isJwtValid, parseServerSessionSnapshot as parseSessionCookie };

package/dist/server-session.js

@@ -0,0 +1,3 @@
+import { emptyServerSessionSnapshot, parseServerSessionSnapshot } from "./services/auth/session.js";
+import { isJwtValid } from "./utils/jwt.js";
+export { emptyServerSessionSnapshot, isJwtValid, parseServerSessionSnapshot as parseSessionCookie };

package/dist/services/accounts/accounts.codecs.js

@@ -0,0 +1,17 @@
+import "../../gen/auth/v1/resolve_pb.js";
+//#region src/services/accounts/accounts.codecs.ts
+const keyToProto = {
+	USERNAME: 1,
+	ID: 2,
+	PUBLIC_ID: 2,
+	SMART_ACCOUNT: 3,
+	SMARTACCOUNT: 3
+};
+const ResolveHintCodec = {
+	keyToProto,
+	keyToProtoLookup: keyToProto
+};
+//#endregion
+export { ResolveHintCodec };
+
+//# sourceMappingURL=accounts.codecs.js.map

package/dist/services/accounts/accounts.codecs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.codecs.js","names":[],"sources":["../../../src/services/accounts/accounts.codecs.ts"],"sourcesContent":["import * as ProtoResolve from \"../../gen/auth/v1/resolve_pb.js\";\n\nexport const RESOLVE_HINT_KEYS = [\n    \"USERNAME\",\n    \"ID\",\n    \"PUBLIC_ID\",\n    \"SMART_ACCOUNT\",\n    \"SMARTACCOUNT\",\n] as const;\nexport type ResolveHintKey = (typeof RESOLVE_HINT_KEYS)[number];\n\nconst keyToProto = {\n    USERNAME: ProtoResolve.ResolveHint.USERNAME,\n    ID: ProtoResolve.ResolveHint.ID,\n    PUBLIC_ID: ProtoResolve.ResolveHint.ID,\n    SMART_ACCOUNT: ProtoResolve.ResolveHint.SMART_ACCOUNT,\n    SMARTACCOUNT: ProtoResolve.ResolveHint.SMART_ACCOUNT,\n} satisfies Record<ResolveHintKey, ProtoResolve.ResolveHint>;\n\nexport const ResolveHintCodec = {\n    keyToProto,\n    keyToProtoLookup: keyToProto as Record<string, ProtoResolve.ResolveHint>,\n} as const;\n"],"mappings":";;AAWA,MAAM,aAAa;CACf,UAAA;CACA,IAAA;CACA,WAAA;CACA,eAAA;CACA,cAAA;AACJ;AAEA,MAAa,mBAAmB;CAC5B;CACA,kBAAkB;AACtB"}

package/dist/services/accounts/accounts.d.ts

@@ -0,0 +1,18 @@
+import { PolyesterRequestOptions } from "../../shared/request-options.js";
+import { ResolveAccountInput, ResolvedAccount } from "./accounts.schemas.js";
+import { Transport } from "@connectrpc/connect";
+//#region src/services/accounts/accounts.d.ts
+/**
+ * Resolves user-entered account identifiers into transfer/shareable root or subaccount destinations.
+ */
+declare class AccountsService {
+  #private;
+  constructor(transport: Transport);
+  /**
+   * Resolves a username, opaque account/subaccount ID, or smart-account address into matching destination accounts; set includeSubaccounts for internal-transfer flows that may target subaccounts.
+   */
+  resolve(input: ResolveAccountInput, options?: PolyesterRequestOptions): Promise<ResolvedAccount[]>;
+}
+//#endregion
+export { AccountsService };
+//# sourceMappingURL=accounts.d.ts.map

package/dist/services/accounts/accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.d.ts","names":[],"sources":["../../../src/services/accounts/accounts.ts"],"mappings":";;;;;;;cAiBa;;EAGG,YAAA,WAAW;;;;EAOjB,QACF,OAAO,qBACP,UAAU,0BACX,QAAQ"}

package/dist/services/accounts/accounts.js

@@ -0,0 +1,27 @@
+import { ResolveService } from "../../gen/auth/v1/resolve_pb.js";
+import { toConnectCallOptions } from "../../shared/request-options.js";
+import { ResolveAccountInputSchema, ResolvedAccountArraySchema } from "./accounts.schemas.js";
+import { createClient } from "@connectrpc/connect";
+import * as v from "valibot";
+//#region src/services/accounts/accounts.ts
+/**
+* Resolves user-entered account identifiers into transfer/shareable root or subaccount destinations.
+*/
+var AccountsService = class {
+	#client;
+	constructor(transport) {
+		this.#client = createClient(ResolveService, transport);
+	}
+	/**
+	* Resolves a username, opaque account/subaccount ID, or smart-account address into matching destination accounts; set includeSubaccounts for internal-transfer flows that may target subaccounts.
+	*/
+	async resolve(input, options) {
+		const validatedInput = v.parse(ResolveAccountInputSchema, input);
+		const res = await this.#client.resolveAccount(validatedInput, toConnectCallOptions(options));
+		return v.parse(ResolvedAccountArraySchema, res.matches);
+	}
+};
+//#endregion
+export { AccountsService };
+
+//# sourceMappingURL=accounts.js.map

package/dist/services/accounts/accounts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.js","names":["#client","ProtoResolve.ResolveService"],"sources":["../../../src/services/accounts/accounts.ts"],"sourcesContent":["import { createClient, type Client, type Transport } from \"@connectrpc/connect\";\nimport * as ProtoResolve from \"../../gen/auth/v1/resolve_pb.js\";\nimport * as v from \"valibot\";\nimport {\n    toConnectCallOptions,\n    type PolyesterRequestOptions,\n} from \"../../shared/request-options.js\";\nimport {\n    ResolveAccountInputSchema,\n    ResolvedAccountArraySchema,\n    type ResolveAccountInput,\n    type ResolvedAccount,\n} from \"./accounts.schemas.js\";\n\n/**\n * Resolves user-entered account identifiers into transfer/shareable root or subaccount destinations.\n */\nexport class AccountsService {\n    #client: Client<typeof ProtoResolve.ResolveService>;\n\n    constructor(transport: Transport) {\n        this.#client = createClient(ProtoResolve.ResolveService, transport);\n    }\n\n    /**\n     * Resolves a username, opaque account/subaccount ID, or smart-account address into matching destination accounts; set includeSubaccounts for internal-transfer flows that may target subaccounts.\n     */\n    async resolve(\n        input: ResolveAccountInput,\n        options?: PolyesterRequestOptions,\n    ): Promise<ResolvedAccount[]> {\n        const validatedInput = v.parse(ResolveAccountInputSchema, input);\n        const res = await this.#client.resolveAccount(\n            validatedInput,\n            toConnectCallOptions(options),\n        );\n\n        return v.parse(ResolvedAccountArraySchema, res.matches);\n    }\n}\n"],"mappings":";;;;;;;;;AAiBA,IAAa,kBAAb,MAA6B;CACzB;CAEA,YAAY,WAAsB;EAC9B,KAAKA,UAAU,aAAaC,gBAA6B,SAAS;CACtE;;;;CAKA,MAAM,QACF,OACA,SAC0B;EAC1B,MAAM,iBAAiB,EAAE,MAAM,2BAA2B,KAAK;EAC/D,MAAM,MAAM,MAAM,KAAKD,QAAQ,eAC3B,gBACA,qBAAqB,OAAO,CAChC;EAEA,OAAO,EAAE,MAAM,4BAA4B,IAAI,OAAO;CAC1D;AACJ"}