@opensaas/stack-auth 0.37.0 → 0.39.0

package/dist/config/types.d.ts

@@ -1,5 +1,5 @@
 import type { ListConfig } from '@opensaas/stack-core';
-import type { BetterAuthOptions, User } from 'better-auth';
+import type { BetterAuthOptions, BetterAuthPlugin, User } from 'better-auth';
 import type { ExtendUserListConfig } from '../lists/index.js';
 /**
  * better-auth's own callback shape for `sendVerificationEmail`/
@@ -192,6 +192,13 @@ export type AuthAccessConfig = {
     session?: ListConfig<any>['access'];
     account?: ListConfig<any>['access'];
     verification?: ListConfig<any>['access'];
+    /**
+     * Access control for the `RateLimit` list — only meaningful when
+     * `rateLimit.storage: 'database'` derives it. Per ADR-0013 the list ships
+     * closed like the other four; grant access here (e.g. to inspect throttled
+     * keys in the Admin UI).
+     */
+    rateLimit?: ListConfig<any>['access'];
 };
 export type AuthModelConfig = {
     /**
@@ -321,8 +328,21 @@ export type AuthConfig = {
      */
     schema?: string;
     /**
-     * Which fields to include in the session object
-     * This determines what data is available in access control functions
+     * Which fields to include in the session object passed to access control
+     * functions — a **flattened projection** of the resolved better-auth
+     * session, not the session's own shape. `getSessionFromAuth` (the
+     * implementation the scaffolded `getSession()` calls) resolves each name
+     * against a fixed precedence: a top-level key on the resolved session
+     * object, then the `user` object, then the `session` sub-object.
+     * `userId` is special-cased to the authenticated user's `id`.
+     *
+     * A `customSession` better-auth plugin fully replaces the resolved shape
+     * (it can nest fields anywhere, e.g. under its own custom key) —
+     * reconciling that shape against `sessionFields` is the application's job.
+     * A listed name that can't be resolved is omitted and warns once per
+     * field per process, naming what was checked, rather than silently
+     * becoming `undefined` in an access control function.
+     *
      * @default ['userId', 'email', 'name']
      *
      * @example
@@ -375,11 +395,27 @@ export type AuthConfig = {
      * ]
      * ```
      */
-    betterAuthPlugins?: any[];
+    betterAuthPlugins?: BetterAuthPlugin[];
     /**
      * Rate limiting configuration
      * Controls rate limiting for authentication endpoints
      *
+     * `storage` mirrors better-auth's own `rateLimit.storage` option
+     * (`'memory' | 'database' | 'secondary-storage'`, default `'memory'`). Set
+     * it to `'database'` to persist the limiter across restarts/instances — the
+     * plugin then derives a fifth `RateLimit` Auth list (per ADR-0007) so the
+     * required table exists in the generated Prisma schema, following the same
+     * adoption knobs (`modelName`/`fields`/`tableName`/`schema`) the other four
+     * models carry. Derivation keys off `storage` alone — `enabled: false` with
+     * `storage: 'database'` still produces the list, since better-auth still
+     * expects the table regardless of whether the limiter is currently active
+     * (`enabled` is routinely environment-driven; tying the schema to it would
+     * make dev/prod schemas differ).
+     *
+     * Setting `storage` via `betterAuthOptions.rateLimit.storage` is rejected —
+     * use this option instead, since it also has schema consequences the
+     * passthrough can't apply.
+     *
      * @example
      * ```typescript
      * // Disable rate limiting for testing
@@ -393,6 +429,12 @@ export type AuthConfig = {
      *   window: 60,  // 60 seconds
      *   max: 100,    // 100 requests per window
      * }
+     *
+     * // Persist the limiter in the database (derives a RateLimit list)
+     * rateLimit: {
+     *   enabled: true,
+     *   storage: 'database',
+     * }
      * ```
      */
     rateLimit?: {
@@ -407,7 +449,12 @@ export type AuthConfig = {
          * @default 100
          */
         max?: number;
-    };
+        /**
+         * Where better-auth persists the rate limiter.
+         * @default 'memory'
+         */
+        storage?: 'memory' | 'database' | 'secondary-storage';
+    } & AuthModelConfig;
     /**
      * Escape hatch for better-auth options the stack doesn't model — typed as
      * better-auth's own `BetterAuthOptions` so it stays in step with
@@ -462,7 +509,8 @@ export type NormalizedAuthModelConfig = {
     schema?: string;
 };
 /**
- * Resolved auth model configuration for all four better-auth models.
+ * Resolved auth model configuration for all four better-auth models, plus an
+ * optional fifth for the database-backed rate limiter.
  * Consumed by the Auth-list derivation and the runtime user-key resolution.
  */
 export type NormalizedAuthModels = {
@@ -470,6 +518,12 @@ export type NormalizedAuthModels = {
     session: NormalizedAuthModelConfig;
     account: NormalizedAuthModelConfig;
     verification: NormalizedAuthModelConfig;
+    /**
+     * Present only when `rateLimit.storage === 'database'` — derives a fifth
+     * `RateLimit` Auth list. Absent (not `undefined`-valued) otherwise, so
+     * `Object.values(models)` never yields a model-less entry.
+     */
+    rateLimit?: NormalizedAuthModelConfig;
 };
 /**
  * Internal normalized auth configuration
@@ -489,11 +543,12 @@ export type NormalizedAuthConfig = Required<Omit<AuthConfig, 'emailAndPassword'
      * default (used to wire the datasource `schemas` array during generation).
      */
     schema?: string;
-    betterAuthPlugins: any[];
+    betterAuthPlugins: BetterAuthPlugin[];
     rateLimit?: {
         enabled: boolean;
         window?: number;
         max?: number;
+        storage?: 'memory' | 'database' | 'secondary-storage';
     };
 };
 //# sourceMappingURL=types.d.ts.map

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

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

package/dist/server/build-better-auth-options.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=build-better-auth-options.test.d.ts.map

package/dist/server/build-better-auth-options.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-better-auth-options.test.d.ts","sourceRoot":"","sources":["../../src/server/build-better-auth-options.test.ts"],"names":[],"mappings":""}

package/dist/server/build-better-auth-options.test.js

@@ -0,0 +1,29 @@
+import { describe, it, expectTypeOf } from 'vitest';
+import { buildBetterAuthOptions } from './index.js';
+// `ReturnType<typeof buildBetterAuthOptions>` on the overloaded export itself
+// resolves against its last (generic) signature, not the call-site-selected
+// one — wrapping each call shape in its own ordinary function and reading
+// `ReturnType<typeof wrapper>` instead forces TS to resolve overloads exactly
+// as a real call site would.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- referenced only via `typeof` below
+function callWithNoPlugins(config, context) {
+    return buildBetterAuthOptions(config, context);
+}
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- referenced only via `typeof` below
+function callWithPlugins(config, context, plugins) {
+    return buildBetterAuthOptions(config, context, plugins);
+}
+describe('buildBetterAuthOptions plugin-tuple typing', () => {
+    it('back-compat: the no-argument call still returns the widened BetterAuthOptions', () => {
+        expectTypeOf().toEqualTypeOf();
+    });
+    it('preserves plugin-derived auth.api.* endpoints and a customSession shape', () => {
+        // emailOTP() endpoints exist on the constructed Auth's `api` — erased entirely
+        // when constructed from the widened `BetterAuthOptions` (see #876).
+        expectTypeOf().not.toBeNever();
+        expectTypeOf().not.toBeNever();
+        expectTypeOf().not.toBeNever();
+        expectTypeOf().toEqualTypeOf();
+    });
+});
+//# sourceMappingURL=build-better-auth-options.test.js.map

package/dist/server/build-better-auth-options.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-better-auth-options.test.js","sourceRoot":"","sources":["../../src/server/build-better-auth-options.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAKnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAWnD,8EAA8E;AAC9E,4EAA4E;AAC5E,0EAA0E;AAC1E,8EAA8E;AAC9E,6BAA6B;AAC7B,mGAAmG;AACnG,SAAS,iBAAiB,CACxB,MAAgD,EAChD,OAA+C;IAE/C,OAAO,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAChD,CAAC;AAED,mGAAmG;AACnG,SAAS,eAAe,CACtB,MAAgD,EAChD,OAA+C,EAC/C,OAAoB;IAEpB,OAAO,sBAAsB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;AACzD,CAAC;AAMD,QAAQ,CAAC,4CAA4C,EAAE,GAAG,EAAE;IAC1D,EAAE,CAAC,+EAA+E,EAAE,GAAG,EAAE;QACvF,YAAY,EAAe,CAAC,aAAa,EAAqB,CAAA;IAChE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,yEAAyE,EAAE,GAAG,EAAE;QACjF,+EAA+E;QAC/E,oEAAoE;QACpE,YAAY,EAA4C,CAAC,GAAG,CAAC,SAAS,EAAE,CAAA;QACxE,YAAY,EAAiD,CAAC,GAAG,CAAC,SAAS,EAAE,CAAA;QAC7E,YAAY,EAAkD,CAAC,GAAG,CAAC,SAAS,EAAE,CAAA;QAI9E,YAAY,EAAoB,CAAC,aAAa,EAAqB,CAAA;IACrE,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/server/get-session-from-auth.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=get-session-from-auth.test.d.ts.map

package/dist/server/get-session-from-auth.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-session-from-auth.test.d.ts","sourceRoot":"","sources":["../../src/server/get-session-from-auth.test.ts"],"names":[],"mappings":""}

package/dist/server/get-session-from-auth.test.js

@@ -0,0 +1,25 @@
+import { describe, it, expectTypeOf } from 'vitest';
+import { createAuth, getSessionFromAuth } from './index.js';
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- referenced only via `typeof` below
+function callWithNoPlugins(config, context) {
+    return createAuth(config, context);
+}
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- referenced only via `typeof` below
+function callWithPlugins(config, context, plugins) {
+    return createAuth(config, context, plugins);
+}
+describe('getSessionFromAuth accepts either createAuth() overload (#906)', () => {
+    it('accepts the widened Auth<BetterAuthOptions> instance with no cast', () => {
+        expectTypeOf().toExtend();
+    });
+    it('accepts the narrowed, plugin-typed Auth instance with no cast', () => {
+        // This is the exact case #906 reported as a type error: a `createAuth`
+        // instance narrowed by a plugin tuple, passed straight into
+        // `getSessionFromAuth` without widening it back to `Auth<BetterAuthOptions>`.
+        expectTypeOf().toExtend();
+    });
+    it('return type stays Promise<Session | null>, unchanged by the widened/narrowed instance', () => {
+        expectTypeOf(getSessionFromAuth).returns.toEqualTypeOf();
+    });
+});
+//# sourceMappingURL=get-session-from-auth.test.js.map

package/dist/server/get-session-from-auth.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-session-from-auth.test.js","sourceRoot":"","sources":["../../src/server/get-session-from-auth.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAGnD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAa3D,mGAAmG;AACnG,SAAS,iBAAiB,CACxB,MAAgD,EAChD,OAA+C;IAE/C,OAAO,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AACpC,CAAC;AAED,mGAAmG;AACnG,SAAS,eAAe,CACtB,MAAgD,EAChD,OAA+C,EAC/C,OAAoB;IAEpB,OAAO,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;AAC7C,CAAC;AAKD,QAAQ,CAAC,gEAAgE,EAAE,GAAG,EAAE;IAC9E,EAAE,CAAC,mEAAmE,EAAE,GAAG,EAAE;QAC3E,YAAY,EAAe,CAAC,QAAQ,EAA4C,CAAA;IAClF,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+DAA+D,EAAE,GAAG,EAAE;QACvE,uEAAuE;QACvE,4DAA4D;QAC5D,8EAA8E;QAC9E,YAAY,EAAgB,CAAC,QAAQ,EAA4C,CAAA;IACnF,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,uFAAuF,EAAE,GAAG,EAAE;QAC/F,YAAY,CAAC,kBAAkB,CAAC,CAAC,OAAO,CAAC,aAAa,EAA2B,CAAA;IACnF,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/server/index.d.ts

@@ -1,6 +1,18 @@
-import { betterAuth } from 'better-auth';
-import type { BetterAuthOptions } from 'better-auth';
-import type { OpenSaasConfig, AccessContext } from '@opensaas/stack-core';
+import { nextCookies } from 'better-auth/next-js';
+import type { Auth, BetterAuthOptions, BetterAuthPlugin } from 'better-auth';
+import type { OpenSaasConfig, AccessContext, Session } from '@opensaas/stack-core';
+/**
+ * The `BetterAuthOptions` shape produced when an app's own plugin tuple is
+ * passed to `buildBetterAuthOptions()`/`createAuth()` — the tuple plus the
+ * `nextCookies()` plugin the stack always appends last. Carrying the literal
+ * tuple type (rather than the widened `BetterAuthPlugin[]`) is what lets
+ * `betterAuth()` re-infer plugin endpoints (e.g. `emailOTP()`'s
+ * `api.signInEmailOTP`) and a `customSession()` plugin's replaced session
+ * shape from the resulting options object.
+ */
+type ResolvedBetterAuthOptions<TPlugins extends readonly BetterAuthPlugin[]> = Omit<BetterAuthOptions, 'plugins'> & {
+    plugins: [...TPlugins, ReturnType<typeof nextCookies>];
+};
 /**
  * Build the `BetterAuthOptions` a better-auth instance for this OpenSaas
  * config should be constructed with — the same options `createAuth()` uses
@@ -10,42 +22,123 @@ import type { OpenSaasConfig, AccessContext } from '@opensaas/stack-core';
  * authoritative for everything it models; the app's additions on top become
  * an explicit, reviewable diff instead of a parallel, hand-duplicated config.
  *
- * @example
+ * Called with just `(config, context)`, the return type is the widened
+ * `BetterAuthOptions` — `betterAuth()` infers its plugin/session types from
+ * the *literal* type of the options object, so constructing from this
+ * widened return erases plugin endpoints (e.g. `emailOTP()`'s
+ * `api.signInEmailOTP`) and a `customSession()` plugin's replaced session
+ * shape. **If your app reads `auth.api.*` in typed code and uses either of
+ * those, pass its plugin tuple as the third argument** — the exact same
+ * array already passed to `authPlugin({ betterAuthPlugins })` — so the
+ * return type carries the literal tuple instead:
+ *
  * ```typescript
  * import { betterAuth } from 'better-auth'
+ * import { emailOTP } from 'better-auth/plugins'
  * import { buildBetterAuthOptions } from '@opensaas/stack-auth/server'
  *
+ * export const appBetterAuthPlugins = [emailOTP()] // same array passed to authPlugin({ betterAuthPlugins })
+ *
  * export const auth = betterAuth({
- *   ...(await buildBetterAuthOptions(config, context)),
+ *   ...(await buildBetterAuthOptions(config, context, appBetterAuthPlugins)),
  *   databaseHooks: { user: { create: { after: syncDomainUser } } },
  * })
+ * // auth.api.signInEmailOTP / auth.api.getSession()'s customSession shape are now typed.
  * ```
+ *
+ * The supplied tuple is for typing only — the array actually used at runtime
+ * is always the one resolved from `authPlugin({ betterAuthPlugins })`, with
+ * exactly one `nextCookies()` appended last. Passing a tuple that isn't the
+ * same plugin instances in the same order throws, so the two can't silently
+ * drift apart.
+ *
+ * Note `createAuth()`'s lazy Proxy does not behave identically to a real
+ * `Auth` instance for every property (see its own doc comment) — reach for
+ * this builder plus `betterAuth()` instead when the app reads `auth.api.*`
+ * in typed code.
  */
 export declare function buildBetterAuthOptions(opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>, context: AccessContext | Promise<AccessContext>): Promise<BetterAuthOptions>;
+export declare function buildBetterAuthOptions<const TPlugins extends readonly BetterAuthPlugin[]>(opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>, context: AccessContext | Promise<AccessContext>, plugins: TPlugins): Promise<ResolvedBetterAuthOptions<TPlugins>>;
 /**
  * Create a better-auth instance from OpenSaas config
  * This should be called once at app startup
  *
- * @example
+ * Returns a lazy `Proxy` (see the caveat below), typed as `Auth<BetterAuthOptions>`
+ * when called with just `(config, context)` — the widened type, same erasure
+ * caveat as {@link buildBetterAuthOptions}'s no-argument form. **If your app
+ * reads `auth.api.*` in typed code and relies on a plugin's endpoints (e.g.
+ * `emailOTP()`) or a `customSession()`'s replaced session shape, pass its
+ * plugin tuple as the third argument** — the exact same array already passed
+ * to `authPlugin({ betterAuthPlugins })` — so the declared type carries the
+ * literal tuple instead:
+ *
  * ```typescript
  * // lib/auth.ts
  * import { createAuth } from '@opensaas/stack-auth/server'
  * import config from '../opensaas.config'
  * import { rawOpensaasContext } from '@/.opensaas/context'
  *
- * export const auth = createAuth(config, rawOpensaasContext)
+ * export const appBetterAuthPlugins = [emailOTP()] // same array passed to authPlugin({ betterAuthPlugins })
+ *
+ * export const auth = createAuth(config, rawOpensaasContext, appBetterAuthPlugins)
  * ```
+ *
+ * As with the builder, the supplied tuple is for typing only, and a tuple
+ * that isn't the same plugin instances in the same order throws.
+ *
+ * **Proxy caveat:** the lazy `Proxy` this returns does not behave identically
+ * to a real `Auth` instance for every property — every access, including a
+ * non-function property, is surfaced through an `async` wrapper (so e.g.
+ * `auth.options` reads back as a `Promise`, not the plain object a real
+ * instance would return synchronously). The declared type does not model
+ * this difference; where it matters, reach for {@link buildBetterAuthOptions}
+ * plus `betterAuth()` instead, which constructs a real instance.
  */
-export declare function createAuth(opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>, context: AccessContext | Promise<AccessContext>): import("better-auth").Auth<BetterAuthOptions>;
+export declare function createAuth(opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>, context: AccessContext | Promise<AccessContext>): Auth<BetterAuthOptions>;
+export declare function createAuth<const TPlugins extends readonly BetterAuthPlugin[]>(opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>, context: AccessContext | Promise<AccessContext>, plugins: TPlugins): Auth<ResolvedBetterAuthOptions<TPlugins>>;
 /**
- * Get session from better-auth and transform it to OpenSaas session format.
+ * Get session from better-auth and transform it to OpenSaas session format —
+ * a flattened projection of `sessionFields` off the *resolved* session
+ * object, not just its `user` sub-object. This is what makes a
+ * `customSession` plugin's fields (added at the top level, or a
+ * session-only field like the admin plugin's `impersonatedBy`) reachable.
+ * See the `sessionFields` reference for the resolution precedence.
+ *
+ * Returns `null` only when there is genuinely no session — a resolved
+ * session with no `user` key (a `customSession` plugin that dropped it) is
+ * still a session and still gets projected, never misreported as anonymous.
+ * A listed field that can't be resolved from the session shape is omitted
+ * and warns once per field per process (see `warnUnresolvedSessionField`)
+ * instead of silently vanishing into an access-control function reading
+ * `undefined`.
+ *
+ * Errors from the underlying `auth.api.getSession()` call propagate rather
+ * than becoming `null` — collapsing a lookup failure (e.g. a session-store
+ * outage) into "anonymous" is indistinguishable from a mass sign-out under
+ * fail-closed access control, so the caller must see it.
+ *
+ * Not called by any generated code before this helper existed — apps used to
+ * hand-roll this same transform against `auth.api.getSession({ headers:
+ * await headers() })`. Exported as the single reusable implementation; pass
+ * the caller's request headers (e.g. Next.js `await headers()` in a Server
+ * Component/action) so a session cookie can actually be resolved.
  *
- * Not called by any generated code today — apps currently hand-roll this same
- * transform against `auth.api.getSession({ headers: await headers() })` (see
- * `examples/starter-auth/lib/auth.ts`). Exported as a reusable helper for that
- * pattern; pass the caller's request headers (e.g. Next.js `await headers()`
- * in a Server Component/action) so a session cookie can actually be resolved.
+ * `auth` is typed structurally over just the one member this function reads
+ * — `api.getSession` — rather than a single concrete `Auth<Options>`
+ * instantiation, so it accepts an instance from either `createAuth()`
+ * overload: the widened `Auth<BetterAuthOptions>`, or the narrowed
+ * `Auth<ResolvedBetterAuthOptions<TPlugins>>` returned when a plugin tuple is
+ * passed. `TResolvedSession` is inferred from whatever `auth.api.getSession`
+ * actually returns (the default `{ session, user }` shape, or a
+ * `customSession` plugin's replaced shape) — it is not constrained, so no
+ * `any`/`unknown` is introduced at the call boundary.
  */
-export declare function getSessionFromAuth(auth: ReturnType<typeof betterAuth>, sessionFields: string[], headers: Headers): Promise<Record<string, unknown> | null>;
+export declare function getSessionFromAuth<TResolvedSession>(auth: {
+    api: {
+        getSession: (args: {
+            headers: Headers;
+        }) => Promise<TResolvedSession>;
+    };
+}, sessionFields: string[], headers: Headers): Promise<Session | null>;
 export type { BetterAuthOptions };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGxC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAkHzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,CAC1C,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,EACxD,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GAC9C,OAAO,CAAC,iBAAiB,CAAC,CA+H5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,EACxD,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,iDAoEhD;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,EACnC,aAAa,EAAE,MAAM,EAAE,EACvB,OAAO,EAAE,OAAO,2CAwBjB;AAED,YAAY,EAAE,iBAAiB,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAIlF;;;;;;;;GAQG;AACH,KAAK,yBAAyB,CAAC,QAAQ,SAAS,SAAS,gBAAgB,EAAE,IAAI,IAAI,CACjF,iBAAiB,EACjB,SAAS,CACV,GAAG;IACF,OAAO,EAAE,CAAC,GAAG,QAAQ,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,CAAA;CACvD,CAAA;AA8JD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,sBAAsB,CAC1C,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,EACxD,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GAC9C,OAAO,CAAC,iBAAiB,CAAC,CAAA;AAC7B,wBAAsB,sBAAsB,CAAC,KAAK,CAAC,QAAQ,SAAS,SAAS,gBAAgB,EAAE,EAC7F,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,EACxD,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,EAC/C,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,yBAAyB,CAAC,QAAQ,CAAC,CAAC,CAAA;AAkJ/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,UAAU,CACxB,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,EACxD,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GAC9C,IAAI,CAAC,iBAAiB,CAAC,CAAA;AAC1B,wBAAgB,UAAU,CAAC,KAAK,CAAC,QAAQ,SAAS,SAAS,gBAAgB,EAAE,EAC3E,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,EACxD,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,EAC/C,OAAO,EAAE,QAAQ,GAChB,IAAI,CAAC,yBAAyB,CAAC,QAAQ,CAAC,CAAC,CAAA;AA8I5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,kBAAkB,CAAC,gBAAgB,EACvD,IAAI,EAAE;IAAE,GAAG,EAAE;QAAE,UAAU,EAAE,CAAC,IAAI,EAAE;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAA;KAAE,CAAA;CAAE,EACxF,aAAa,EAAE,MAAM,EAAE,EACvB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAoBzB;AAED,YAAY,EAAE,iBAAiB,EAAE,CAAA"}