@mt-tl/server 0.1.0

package/dist/core/context.d.ts

@@ -0,0 +1,57 @@
+import { type Logger, type RpcContext, type SessionEffect } from '@mt-tl/tl';
+import type { UpdateEmitter } from './updates.js';
+/**
+ * Handler-facing context: the request data plus session effects, server-push,
+ * and a per-request value bag. Business dependencies are NOT here — a handler
+ * (or a plugin) closes over its service (Style A DI), so `ctx` carries only
+ * request-scoped + cross-cutting concerns. Handlers stay thin: call the service,
+ * shape the result, optionally `login()`/`push()`.
+ */
+export interface HandlerCtx {
+    /** Raw request context forwarded by the gateway (sessionId, authKeyId, ip, …). */
+    readonly request: RpcContext;
+    /** The bound **subject** — your app's internal user id (opaque string, e.g. a
+     * uuid), shareable across your services. `undefined` if the auth key is
+     * anonymous; on an `auth: true` method it is guaranteed present, so
+     * `ctx.subject!` is safe there. Distinct from any wire `user_id:int` your TL
+     * schema exposes — map between them in your app (see the demo `users` module). */
+    readonly subject: string | undefined;
+    /** The TL layer this request came in on (the client's negotiated layer).
+     * Read-only — layer negotiation is the protocol's job. Branch on it when an
+     * old client needs a different response shape. */
+    readonly layer: number;
+    /** Per-request logger (a child bound with method/subject) — log with the same
+     * style as the framework so app and engine lines interleave coherently. */
+    readonly log: Logger;
+    /** Low-level update emitter behind {@link push}; prefer `ctx.push(subject, update)`. */
+    readonly updates: UpdateEmitter;
+    /** Collected session effects (applied by the gateway). */
+    readonly effects: readonly SessionEffect[];
+    /** Bind the auth key to a `subject` — your internal user id (device login). */
+    login(subject: string): void;
+    /** Unbind the auth key (logout). */
+    logout(): void;
+    /** Revoke the auth key entirely. */
+    revoke(): void;
+    /** Push a TL update to a `subject` (delivered via the update bus to whatever node holds them). */
+    push(subject: string, update: unknown): Promise<void>;
+    /**
+     * Push to a specific auth key — including an anonymous (not-logged-in)
+     * connection, e.g. to deliver API to a client before it registers. Pass
+     * `ctx.request.authKeyId` for the current connection. No pts (anonymous
+     * connections have no durable update state).
+     */
+    pushToAuthKey(authKeyId: string, update: unknown): Promise<void>;
+    /** Stash a value for the handler (e.g. data a pre-handler already fetched). */
+    set(key: string, value: unknown): void;
+    /** Read a value stashed earlier in this request. */
+    get<T = unknown>(key: string): T | undefined;
+    /** @deprecated use {@link login} */
+    bindUser(subject: string): void;
+    /** @deprecated use {@link logout} */
+    unbindUser(): void;
+    /** @deprecated use {@link revoke} */
+    revokeKey(): void;
+}
+export declare function createHandlerCtx(request: RpcContext, updates: UpdateEmitter, log?: Logger): HandlerCtx;
+//# sourceMappingURL=context.d.ts.map

package/dist/core/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,MAAM,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAA;AACxF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACvB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;IAC5B;;;;sFAIkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC;;sDAEkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;+EAC2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAA;IAG1C,+EAA+E;IAC/E,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,oCAAoC;IACpC,MAAM,IAAI,IAAI,CAAA;IACd,oCAAoC;IACpC,MAAM,IAAI,IAAI,CAAA;IAGd,kGAAkG;IAClG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD;;;;;OAKG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAGhE,+EAA+E;IAC/E,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;IACtC,oDAAoD;IACpD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAA;IAG5C,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,qCAAqC;IACrC,UAAU,IAAI,IAAI,CAAA;IAClB,qCAAqC;IACrC,SAAS,IAAI,IAAI,CAAA;CACpB;AAED,wBAAgB,gBAAgB,CAC5B,OAAO,EAAE,UAAU,EACnB,OAAO,EAAE,aAAa,EACtB,GAAG,GAAE,MAAmB,GACzB,UAAU,CAwBZ"}

package/dist/core/context.js

@@ -0,0 +1,27 @@
+import { noopLogger } from '@mt-tl/tl';
+export function createHandlerCtx(request, updates, log = noopLogger) {
+    const effects = [];
+    const bag = new Map();
+    const login = (subject) => void effects.push({ type: 'bindUser', subject });
+    const logout = () => void effects.push({ type: 'unbindUser' });
+    const revoke = () => void effects.push({ type: 'revokeKey' });
+    return {
+        request,
+        subject: request.subject,
+        layer: request.apiLayer,
+        log,
+        updates,
+        effects,
+        login,
+        logout,
+        revoke,
+        push: (subject, update) => updates.emit(subject, update),
+        pushToAuthKey: (authKeyId, update) => updates.emitToAuthKey(authKeyId, update),
+        set: (key, value) => void bag.set(key, value),
+        get: (key) => bag.get(key),
+        bindUser: login,
+        unbindUser: logout,
+        revokeKey: revoke,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/core/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAoD,MAAM,WAAW,CAAA;AAiExF,MAAM,UAAU,gBAAgB,CAC5B,OAAmB,EACnB,OAAsB,EACtB,MAAc,UAAU;IAExB,MAAM,OAAO,GAAoB,EAAE,CAAA;IACnC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAmB,CAAA;IACtC,MAAM,KAAK,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAA;IACnF,MAAM,MAAM,GAAG,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAA;IAC9D,MAAM,MAAM,GAAG,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAA;IAC7D,OAAO;QACH,OAAO;QACP,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,KAAK,EAAE,OAAO,CAAC,QAAQ;QACvB,GAAG;QACH,OAAO;QACP,OAAO;QACP,KAAK;QACL,MAAM;QACN,MAAM;QACN,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,MAAe,CAAC;QACjE,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,aAAa,CAAC,SAAS,EAAE,MAAe,CAAC;QACvF,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC;QAC7C,GAAG,EAAE,CAAI,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAkB;QACtD,QAAQ,EAAE,KAAK;QACf,UAAU,EAAE,MAAM;QAClB,SAAS,EAAE,MAAM;KACpB,CAAA;AACL,CAAC"}

package/dist/core/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Business errors. `code`/`message` map straight to the gateway's `rpc_error`
+ * (Telegram-style: 400/401/404/420/500…). Throw these from handlers; anything
+ * else becomes a 500 INTERNAL.
+ */
+export declare class AppError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+/** Invalid input or a violated precondition → `rpc_error 400`. */
+export declare class BadRequestError extends AppError {
+    constructor(message?: string);
+}
+/** Method requires an authorized user but the auth key is anonymous → `rpc_error 401`. */
+export declare class AuthRequiredError extends AppError {
+    constructor(message?: string);
+}
+/** The requested entity does not exist → `rpc_error 404`. */
+export declare class NotFoundError extends AppError {
+    constructor(message?: string);
+}
+/**
+ * Rate-limited → `rpc_error 420 FLOOD_WAIT_<seconds>`. Clients read the number
+ * off the message and retry after that many seconds.
+ */
+export declare class FloodWaitError extends AppError {
+    constructor(seconds: number);
+}
+/** An unexpected server-side failure → `rpc_error 500`. */
+export declare class InternalError extends AppError {
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAE3B,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM;CAKtB;AAED,kEAAkE;AAClE,qBAAa,eAAgB,SAAQ,QAAQ;gBAC7B,OAAO,SAAgB;CAGtC;AAED,0FAA0F;AAC1F,qBAAa,iBAAkB,SAAQ,QAAQ;gBAC/B,OAAO,SAA0B;CAGhD;AAED,6DAA6D;AAC7D,qBAAa,aAAc,SAAQ,QAAQ;gBAC3B,OAAO,SAAc;CAGpC;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,QAAQ;gBAC5B,OAAO,EAAE,MAAM;CAG9B;AAED,2DAA2D;AAC3D,qBAAa,aAAc,SAAQ,QAAQ;gBAC3B,OAAO,SAAa;CAGnC"}

package/dist/core/errors.js

@@ -0,0 +1,47 @@
+/**
+ * Business errors. `code`/`message` map straight to the gateway's `rpc_error`
+ * (Telegram-style: 400/401/404/420/500…). Throw these from handlers; anything
+ * else becomes a 500 INTERNAL.
+ */
+export class AppError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = new.target.name;
+    }
+}
+/** Invalid input or a violated precondition → `rpc_error 400`. */
+export class BadRequestError extends AppError {
+    constructor(message = 'BAD_REQUEST') {
+        super(400, message);
+    }
+}
+/** Method requires an authorized user but the auth key is anonymous → `rpc_error 401`. */
+export class AuthRequiredError extends AppError {
+    constructor(message = 'AUTH_KEY_UNREGISTERED') {
+        super(401, message);
+    }
+}
+/** The requested entity does not exist → `rpc_error 404`. */
+export class NotFoundError extends AppError {
+    constructor(message = 'NOT_FOUND') {
+        super(404, message);
+    }
+}
+/**
+ * Rate-limited → `rpc_error 420 FLOOD_WAIT_<seconds>`. Clients read the number
+ * off the message and retry after that many seconds.
+ */
+export class FloodWaitError extends AppError {
+    constructor(seconds) {
+        super(420, `FLOOD_WAIT_${seconds}`);
+    }
+}
+/** An unexpected server-side failure → `rpc_error 500`. */
+export class InternalError extends AppError {
+    constructor(message = 'INTERNAL') {
+        super(500, message);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAElB;IADb,YACa,IAAY,EACrB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAA;QAHL,SAAI,GAAJ,IAAI,CAAQ;QAIrB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAA;IAC/B,CAAC;CACJ;AAED,kEAAkE;AAClE,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IACzC,YAAY,OAAO,GAAG,aAAa;QAC/B,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;IACvB,CAAC;CACJ;AAED,0FAA0F;AAC1F,MAAM,OAAO,iBAAkB,SAAQ,QAAQ;IAC3C,YAAY,OAAO,GAAG,uBAAuB;QACzC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;IACvB,CAAC;CACJ;AAED,6DAA6D;AAC7D,MAAM,OAAO,aAAc,SAAQ,QAAQ;IACvC,YAAY,OAAO,GAAG,WAAW;QAC7B,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;IACvB,CAAC;CACJ;AAED;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACxC,YAAY,OAAe;QACvB,KAAK,CAAC,GAAG,EAAE,cAAc,OAAO,EAAE,CAAC,CAAA;IACvC,CAAC;CACJ;AAED,2DAA2D;AAC3D,MAAM,OAAO,aAAc,SAAQ,QAAQ;IACvC,YAAY,OAAO,GAAG,UAAU;QAC5B,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;IACvB,CAAC;CACJ"}

package/dist/core/index.d.ts

@@ -0,0 +1,5 @@
+export * from './errors.js';
+export * from './updates.js';
+export * from './context.js';
+export * from './rpc.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA"}

package/dist/core/index.js

@@ -0,0 +1,5 @@
+export * from './errors.js';
+export * from './updates.js';
+export * from './context.js';
+export * from './rpc.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA"}

package/dist/core/rpc.d.ts

@@ -0,0 +1,83 @@
+import type { Logger, RpcRequest, RpcResponse } from '@mt-tl/tl';
+import { type HandlerCtx } from './context.js';
+import type { UpdateEmitter } from './updates.js';
+/**
+ * Shape of one TL method's I/O. An app's generated `RpcMethods` (one entry per
+ * method, `{ params, result }`) structurally matches `RpcMethodMap` — the
+ * framework is generic over it, not bound to any specific schema.
+ */
+export interface RpcMethodSpec {
+    params: unknown;
+    result: unknown;
+}
+export type RpcMethodMap = Record<string, RpcMethodSpec>;
+/** A typed handler for one method `M` of the app's method map `RM`. */
+export type RpcHandlerOf<RM extends Record<keyof RM, RpcMethodSpec>, M extends keyof RM> = (params: RM[M]['params'], ctx: HandlerCtx) => Promise<RM[M]['result']>;
+/**
+ * A reusable pre-handler. Runs before the handler with the same `ctx`; throw an
+ * `AppError` to reject (→ `rpc_error`), or `ctx.set(...)` to pass data forward.
+ * Method-agnostic, so `params` is `unknown` (narrow if a hook needs them).
+ */
+export type Hook = (params: unknown, ctx: HandlerCtx) => Promise<void> | void;
+/** Identity helper for authoring a reusable hook. */
+export declare function defineHook(fn: Hook): Hook;
+export type RpcEntryOf<RM extends Record<keyof RM, RpcMethodSpec>, M extends keyof RM> = RpcHandlerOf<RM, M> | {
+    auth?: boolean;
+    preHandlers?: Hook[];
+    handler: RpcHandlerOf<RM, M>;
+};
+/** A fully-typed module of RPC handlers, keyed by the app's method names. */
+export type RpcModuleOf<RM extends Record<keyof RM, RpcMethodSpec>> = {
+    [M in keyof RM]?: RpcEntryOf<RM, M>;
+};
+type LooseHandler = (params: never, ctx: HandlerCtx) => Promise<unknown>;
+type LooseEntry = LooseHandler | {
+    auth?: boolean;
+    preHandlers?: Hook[];
+    handler: LooseHandler;
+};
+/** Erased module shape — what module factories expose and the registry consumes. */
+export type RpcModule = Record<string, LooseEntry | undefined>;
+/**
+ * Creates a `defineRpc` typed against the app's generated `RpcMethods`. Use once
+ * per app: `export const { defineRpc } = createRpc<RpcMethods>()`, then write
+ * modules with full param/result inference per method.
+ */
+export declare function createRpc<RM extends Record<keyof RM, RpcMethodSpec>>(): {
+    defineRpc(mod: RpcModuleOf<RM>): RpcModuleOf<RM>;
+};
+/** Untyped authoring helper — for fixtures/demos with no generated types. */
+export declare function defineRpc(mod: RpcModule): RpcModule;
+interface Route {
+    handler: (params: unknown, ctx: HandlerCtx) => Promise<unknown>;
+    auth: boolean;
+    preHandlers: Hook[];
+}
+/**
+ * The method table behind a server. `createServer().method(...)` adds to one for
+ * you; you rarely touch it directly (pass your own via `createServer(config, {
+ * registry })` only for advanced wiring or tests).
+ */
+export declare class RpcRegistry {
+    private routes;
+    /** Register a module of handlers (later entries override earlier same-named ones). */
+    add(mod: RpcModule): this;
+    get(method: string): Route | undefined;
+    /** Registered method names. */
+    methods(): string[];
+    get size(): number;
+}
+/** Process-wide dependencies {@link dispatchRpc} threads into each handler's `ctx`. */
+export interface DispatchDeps {
+    updates: UpdateEmitter;
+    /** Observability sink; a per-request child becomes `ctx.log`. Defaults to no-op. */
+    logger?: Logger;
+}
+/**
+ * Routes a forwarded request to its handler and returns the gateway envelope.
+ * 404 for unknown methods, 401 for auth-required methods on an anonymous key,
+ * AppError → its code, anything else → 500. Effects accompany result or error.
+ */
+export declare function dispatchRpc(registry: RpcRegistry, request: RpcRequest, deps: DispatchDeps): Promise<RpcResponse>;
+export {};
+//# sourceMappingURL=rpc.d.ts.map

package/dist/core/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../../src/core/rpc.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAW,MAAM,WAAW,CAAA;AAEzE,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAA;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC1B,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;CAClB;AACD,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;AAExD,uEAAuE;AACvE,MAAM,MAAM,YAAY,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,EAAE,CAAC,SAAS,MAAM,EAAE,IAAI,CACvF,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EACvB,GAAG,EAAE,UAAU,KACd,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;AAE7B;;;;GAIG;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;AAE7E,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,EAAE,EAAE,IAAI,GAAG,IAAI,CAEzC;AAED,MAAM,MAAM,UAAU,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,EAAE,CAAC,SAAS,MAAM,EAAE,IAC/E,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC,GACnB;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC;IAAC,OAAO,EAAE,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;CAAE,CAAA;AAE5E,6EAA6E;AAC7E,MAAM,MAAM,WAAW,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;CAAE,CAAA;AAG7G,KAAK,YAAY,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;AACxE,KAAK,UAAU,GAAG,YAAY,GAAG;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAA;AAChG,oFAAoF;AACpF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC,CAAA;AAE9D;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC;mBAE7C,WAAW,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,EAAE,CAAC;EAIvD;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,GAAG,EAAE,SAAS,GAAG,SAAS,CAEnD;AAED,UAAU,KAAK;IACX,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/D,IAAI,EAAE,OAAO,CAAA;IACb,WAAW,EAAE,IAAI,EAAE,CAAA;CACtB;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,MAAM,CAA2B;IAEzC,sFAAsF;IACtF,GAAG,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI;IAgBzB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAItC,+BAA+B;IAC/B,OAAO,IAAI,MAAM,EAAE;IAInB,IAAI,IAAI,IAAI,MAAM,CAEjB;CACJ;AAED,uFAAuF;AACvF,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,aAAa,CAAA;IACtB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC7B,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,YAAY,GACnB,OAAO,CAAC,WAAW,CAAC,CAiCtB"}

package/dist/core/rpc.js

@@ -0,0 +1,102 @@
+import { fromJson, toJson, noopLogger } from '@mt-tl/tl';
+import { AppError } from './errors.js';
+import { createHandlerCtx } from './context.js';
+/** Identity helper for authoring a reusable hook. */
+export function defineHook(fn) {
+    return fn;
+}
+/**
+ * Creates a `defineRpc` typed against the app's generated `RpcMethods`. Use once
+ * per app: `export const { defineRpc } = createRpc<RpcMethods>()`, then write
+ * modules with full param/result inference per method.
+ */
+export function createRpc() {
+    return {
+        defineRpc(mod) {
+            return mod;
+        },
+    };
+}
+/** Untyped authoring helper — for fixtures/demos with no generated types. */
+export function defineRpc(mod) {
+    return mod;
+}
+/**
+ * The method table behind a server. `createServer().method(...)` adds to one for
+ * you; you rarely touch it directly (pass your own via `createServer(config, {
+ * registry })` only for advanced wiring or tests).
+ */
+export class RpcRegistry {
+    routes = new Map();
+    /** Register a module of handlers (later entries override earlier same-named ones). */
+    add(mod) {
+        for (const [name, entry] of Object.entries(mod)) {
+            if (!entry)
+                continue;
+            const route = typeof entry === 'function'
+                ? { handler: entry, auth: true, preHandlers: [] }
+                : {
+                    handler: entry.handler,
+                    auth: entry.auth ?? true,
+                    preHandlers: entry.preHandlers ?? [],
+                };
+            this.routes.set(name, route);
+        }
+        return this;
+    }
+    get(method) {
+        return this.routes.get(method);
+    }
+    /** Registered method names. */
+    methods() {
+        return [...this.routes.keys()];
+    }
+    get size() {
+        return this.routes.size;
+    }
+}
+/**
+ * Routes a forwarded request to its handler and returns the gateway envelope.
+ * 404 for unknown methods, 401 for auth-required methods on an anonymous key,
+ * AppError → its code, anything else → 500. Effects accompany result or error.
+ */
+export async function dispatchRpc(registry, request, deps) {
+    const route = registry.get(request.method);
+    if (!route)
+        return { error: { code: 404, message: 'METHOD_NOT_FOUND' } };
+    if (route.auth && request.context.subject === undefined) {
+        return { error: { code: 401, message: 'AUTH_KEY_UNREGISTERED' } };
+    }
+    // Bind the full request identity onto every handler line: reqId (the client's
+    // msg_id) ties the context to one request, plus authKeyId/sessionId/subject.
+    const log = (deps.logger ?? noopLogger).child({
+        reqId: request.id,
+        method: request.method,
+        subject: request.context.subject,
+        authKeyId: request.context.authKeyId,
+        sessionId: request.context.sessionId,
+    });
+    const ctx = createHandlerCtx(request.context, deps.updates, log);
+    try {
+        const params = fromJson(request.params);
+        for (const hook of route.preHandlers)
+            await hook(params, ctx);
+        const result = await route.handler(params, ctx);
+        return { result: toJson(result), effects: effectsOf(ctx) };
+    }
+    catch (err) {
+        if (err instanceof AppError) {
+            // Expected business rejection (→ rpc_error with the app's code).
+            log.debug('handler.reject', { code: err.code, error: err.message });
+            return { error: { code: err.code, message: err.message }, effects: effectsOf(ctx) };
+        }
+        // Unexpected throw — a real bug. Log it with the stack (errorStack-gated) so
+        // the failed request is traceable; the client only sees a generic 500.
+        log.error('handler.fail', { err });
+        return { error: { code: 500, message: 'INTERNAL' }, effects: effectsOf(ctx) };
+    }
+}
+function effectsOf(ctx) {
+    return ctx.effects.length ? [...ctx.effects] : undefined;
+}
+//# sourceMappingURL=rpc.js.map

package/dist/core/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../src/core/rpc.ts"],"names":[],"mappings":"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"}

package/dist/core/updates.d.ts

@@ -0,0 +1,56 @@
+import type { JsonValue } from '@mt-tl/tl';
+/**
+ * Durable per-subject update log: assigns the next `pts` and persists the update.
+ * `updates.getDifference` reads from here. The gateway never sees pts — it only
+ * delivers live updates best-effort; correctness is this log + getDifference.
+ * Keyed by `subject` (your internal user id), like the rest of the push path.
+ */
+export interface UpdateLog {
+    append(subject: string, update: JsonValue): Promise<{
+        pts: number;
+    }>;
+    /** Updates with pts in (sincePts, +inf], for getDifference. */
+    since(subject: string, sincePts: number): Promise<Array<{
+        pts: number;
+        update: JsonValue;
+    }>>;
+    currentPts(subject: string): Promise<number>;
+}
+/** Publishes a routed live update onto the update bus (in-memory, or Redis pub/sub in prod). */
+export type UpdatePublish = (msg: {
+    subject?: string;
+    authKeyId?: string;
+    update: JsonValue;
+    pts?: number;
+}) => Promise<void>;
+/**
+ * Emits a server update. `emit(subject, …)` is the common path: append to the
+ * durable log (assigns pts) then publish — this backs `ctx.push`. `emitToAuthKey`
+ * targets a specific (possibly anonymous) connection by auth key, with no pts
+ * (anonymous connections have no durable update state).
+ */
+export interface UpdateEmitter {
+    emit(subject: string, update: JsonValue): Promise<void>;
+    emitToAuthKey(authKeyId: string, update: JsonValue): Promise<void>;
+}
+/** The default {@link UpdateEmitter}: log (for pts) then publish to the bus. */
+export declare class LoggingUpdateEmitter implements UpdateEmitter {
+    private readonly log;
+    private readonly publish;
+    constructor(log: UpdateLog, publish: UpdatePublish);
+    emit(subject: string, update: JsonValue): Promise<void>;
+    emitToAuthKey(authKeyId: string, update: JsonValue): Promise<void>;
+}
+/** In-memory update log (single process / tests). Use a Mongo impl in prod. */
+export declare class InMemoryUpdateLog implements UpdateLog {
+    private bySubject;
+    append(subject: string, update: JsonValue): Promise<{
+        pts: number;
+    }>;
+    since(subject: string, sincePts: number): Promise<Array<{
+        pts: number;
+        update: JsonValue;
+    }>>;
+    currentPts(subject: string): Promise<number>;
+}
+//# sourceMappingURL=updates.d.ts.map

package/dist/core/updates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updates.d.ts","sourceRoot":"","sources":["../../src/core/updates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACtB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACpE,+DAA+D;IAC/D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC,CAAA;IAC5F,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CAC/C;AAED,gGAAgG;AAChG,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,SAAS,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,CAAA;CACf,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAEnB;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC1B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACrE;AAED,gFAAgF;AAChF,qBAAa,oBAAqB,YAAW,aAAa;IAElD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,aAAa;IAGrC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvD,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CAG3E;AAED,+EAA+E;AAC/E,qBAAa,iBAAkB,YAAW,SAAS;IAC/C,OAAO,CAAC,SAAS,CAA+D;IAE1E,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAOpE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;IAG5F,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAGrD"}

package/dist/core/updates.js

@@ -0,0 +1,34 @@
+/** The default {@link UpdateEmitter}: log (for pts) then publish to the bus. */
+export class LoggingUpdateEmitter {
+    log;
+    publish;
+    constructor(log, publish) {
+        this.log = log;
+        this.publish = publish;
+    }
+    async emit(subject, update) {
+        const { pts } = await this.log.append(subject, update);
+        await this.publish({ subject, update, pts });
+    }
+    async emitToAuthKey(authKeyId, update) {
+        await this.publish({ authKeyId, update });
+    }
+}
+/** In-memory update log (single process / tests). Use a Mongo impl in prod. */
+export class InMemoryUpdateLog {
+    bySubject = new Map();
+    async append(subject, update) {
+        const list = this.bySubject.get(subject) ?? [];
+        const pts = (list.at(-1)?.pts ?? 0) + 1;
+        list.push({ pts, update });
+        this.bySubject.set(subject, list);
+        return { pts };
+    }
+    async since(subject, sincePts) {
+        return (this.bySubject.get(subject) ?? []).filter(e => e.pts > sincePts);
+    }
+    async currentPts(subject) {
+        return this.bySubject.get(subject)?.at(-1)?.pts ?? 0;
+    }
+}
+//# sourceMappingURL=updates.js.map

package/dist/core/updates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updates.js","sourceRoot":"","sources":["../../src/core/updates.ts"],"names":[],"mappings":"AAkCA,gFAAgF;AAChF,MAAM,OAAO,oBAAoB;IAER;IACA;IAFrB,YACqB,GAAc,EACd,OAAsB;QADtB,QAAG,GAAH,GAAG,CAAW;QACd,YAAO,GAAP,OAAO,CAAe;IACxC,CAAC;IAEJ,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,MAAiB;QACzC,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QACtD,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IAChD,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,SAAiB,EAAE,MAAiB;QACpD,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAA;IAC7C,CAAC;CACJ;AAED,+EAA+E;AAC/E,MAAM,OAAO,iBAAiB;IAClB,SAAS,GAAG,IAAI,GAAG,EAAqD,CAAA;IAEhF,KAAK,CAAC,MAAM,CAAC,OAAe,EAAE,MAAiB;QAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAA;QAC9C,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;QACvC,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;QACjC,OAAO,EAAE,GAAG,EAAE,CAAA;IAClB,CAAC;IACD,KAAK,CAAC,KAAK,CAAC,OAAe,EAAE,QAAgB;QACzC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,QAAQ,CAAC,CAAA;IAC5E,CAAC;IACD,KAAK,CAAC,UAAU,CAAC,OAAe;QAC5B,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAA;IACxD,CAAC;CACJ"}

package/dist/create-server.d.ts

@@ -0,0 +1,89 @@
+import type { KeyObject } from 'node:crypto';
+import { type MTProtoConfig } from './lib.js';
+import { type Logger, type MigrationRegistry, type RpcRequest, type RpcResponse } from '@mt-tl/tl';
+import { RpcRegistry, type Hook, type HandlerCtx, type RpcMethodSpec } from './core/index.js';
+/** Per-method options. */
+export interface MethodOpts {
+    /** Require an authorized auth key (a bound `subject`). Defaults to `true`. */
+    auth?: boolean;
+    /** Reusable pre-handlers, run in order before the handler (see `defineHook`). */
+    preHandlers?: Hook[];
+}
+/** A handler for method `M` of the app's generated method map `RM`. */
+export type MethodHandler<RM, M extends keyof RM> = RM[M] extends RpcMethodSpec ? (params: RM[M]['params'], ctx: HandlerCtx) => Promise<RM[M]['result']> : never;
+/** A plugin: registers routes on the server, given its declared dependencies. */
+export type Plugin<RM, D = void> = (app: MtprotoServer<RM>, deps: D) => void;
+/**
+ * The server instance (Fastify-style): register routes and listen. It wraps the
+ * MTProto engine + the in-process handler dispatch — there is no broker and no
+ * separate "worker" to wire. Generic over the app's generated `RpcMethods` so
+ * `.method()` infers `params`/`result` (and the method name) per method.
+ */
+export interface MtprotoServer<RM = Record<string, RpcMethodSpec>> {
+    /** Register a route. `auth` defaults to true. */
+    method<M extends keyof RM>(name: M, handler: MethodHandler<RM, M>): this;
+    method<M extends keyof RM>(name: M, opts: MethodOpts, handler: MethodHandler<RM, M>): this;
+    /** Run a plugin, passing its dependencies by value (Style-A DI; omit for `void` deps). */
+    register<D = void>(plugin: Plugin<RM, D>, deps?: D): this;
+    /** Open the configured transports (and the in-process push loop if enabled). */
+    listen(): Promise<void>;
+    close(): Promise<void>;
+    /** Dispatch a request against the registry without a socket — for tests. */
+    inject(req: RpcRequest): Promise<RpcResponse>;
+    /** The server's root logger — use it (or `ctx.log` in a handler) for a unified log style. */
+    readonly log: Logger;
+    /** Registered method names. */
+    readonly methods: string[];
+    /** Bound WebSocket port after {@link listen} (resolves `wsPort: 0`); else `undefined`. */
+    readonly wsPort: number | undefined;
+    /** Bound raw-TCP port after {@link listen} (resolves `tcpPort: 0`); else `undefined`. */
+    readonly tcpPort: number | undefined;
+    /** The server's RSA public key after {@link listen}; clients encrypt the handshake with it. */
+    readonly publicKey: KeyObject | undefined;
+}
+/**
+ * Creates an MTProto server (Fastify-style). Pass the {@link MTProtoConfig},
+ * register routes with `.method()` / plugins with `.register()`, then
+ * `await app.listen()`. The framework owns the whole protocol — transport,
+ * handshake, crypto, sessions, TL (de)serialization, layered encoding,
+ * server-push — you write methods.
+ *
+ * Type it with your generated `RpcMethods` (`createServer<RpcMethods>(config)`)
+ * so every route's name, `params`, and `result` are checked.
+ *
+ * @param config - the server configuration (your app builds it from env).
+ * @param opts.registry - adopt an existing {@link RpcRegistry} instead of a fresh one (advanced/tests).
+ * @param opts.migrations - per-layer migration ladders applied on input/output.
+ * @param opts.logger - structured logger; defaults to `createLogger({ name: config.nodeId })`
+ *   (env-configured via `LOG_LEVEL`/`LOG_FORMAT`). Exposed as `app.log`; handlers get `ctx.log`.
+ *
+ * @example
+ * ```ts
+ * const app = createServer<RpcMethods>(config)
+ * app.method('help.getConfig', { auth: false }, async () => ({ _: 'config' }))
+ * await app.listen()   // opens the WS + raw-TCP carriers
+ * ```
+ */
+export declare function createServer<RM = Record<string, RpcMethodSpec>>(config: MTProtoConfig, opts?: {
+    registry?: RpcRegistry;
+    migrations?: MigrationRegistry;
+    logger?: Logger;
+}): MtprotoServer<RM>;
+/**
+ * Authoring helper for a typed plugin — a function that registers a group of
+ * related routes, taking its dependencies by value (Style-A DI, like
+ * `fastify.register`). Pin it to your `RpcMethods` once (see your app's
+ * `framework.ts`) so routes inside infer their types.
+ *
+ * @example
+ * ```ts
+ * export const walletsPlugin = definePlugin<RpcMethods, { wallets: WalletService }>(
+ *   (app, { wallets }) => {
+ *     app.method('wallets.getBalance', async (_p, ctx) => wallets.balanceOf(ctx.subject!))
+ *   },
+ * )
+ * app.register(walletsPlugin, { wallets: new WalletService() })
+ * ```
+ */
+export declare function definePlugin<RM = Record<string, RpcMethodSpec>, D = void>(fn: Plugin<RM, D>): Plugin<RM, D>;
+//# sourceMappingURL=create-server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-server.d.ts","sourceRoot":"","sources":["../src/create-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAa,KAAK,aAAa,EAAoC,MAAM,UAAU,CAAA;AAC1F,OAAO,EAEH,KAAK,MAAM,EACX,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,WAAW,EACnB,MAAM,WAAW,CAAA;AAClB,OAAO,EACH,WAAW,EAGX,KAAK,IAAI,EACT,KAAK,UAAU,EACf,KAAK,aAAa,EAErB,MAAM,iBAAiB,CAAA;AAExB,0BAA0B;AAC1B,MAAM,WAAW,UAAU;IACvB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,iFAAiF;IACjF,WAAW,CAAC,EAAE,IAAI,EAAE,CAAA;CACvB;AAED,uEAAuE;AACvE,MAAM,MAAM,aAAa,CAAC,EAAE,EAAE,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,aAAa,GACzE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GACtE,KAAK,CAAA;AAEX,iFAAiF;AACjF,MAAM,MAAM,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAC7D,iDAAiD;IACjD,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAAA;IACxE,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAAA;IAC1F,0FAA0F;IAC1F,QAAQ,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAA;IACzD,gFAAgF;IAChF,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,4EAA4E;IAC5E,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC7C,6FAA6F;IAC7F,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAA;IAC1B,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAAA;CAC5C;AAID;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EAC3D,MAAM,EAAE,aAAa,EACrB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,WAAW,CAAC;IAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GACvF,aAAa,CAAC,EAAE,CAAC,CAoEnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,CAE3G"}