alepha 0.13.0 → 0.13.2

package/dist/server-swagger/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["user: UserAccountToken | undefined","ownership: boolean | string | undefined","directives: string[]","params: string[]","openApi: OpenApiDocument","schemas: Record<string, any>","operation: OpenApiOperation","schema: any"],"sources":["../../src/server-security/providers/ServerBasicAuthProvider.ts","../../src/server-security/descriptors/$basicAuth.ts","../../src/server-security/providers/ServerSecurityProvider.ts","../../src/server-security/index.ts","../../src/server-cache/providers/ServerCacheProvider.ts","../../src/server-cache/index.ts","../../src/server-static/descriptors/$serve.ts","../../src/server-static/providers/ServerStaticProvider.ts","../../src/server-static/index.ts","../../src/server-swagger/descriptors/$swagger.ts","../../src/server-swagger/providers/ServerSwaggerProvider.ts","../../src/server-swagger/index.ts"],"sourcesContent":["import { timingSafeEqual } from \"node:crypto\";\nimport { $hook, $inject, Alepha } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  HttpError,\n  type ServerRequest,\n  ServerRouterProvider,\n} from \"alepha/server\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface BasicAuthOptions {\n  username: string;\n  password: string;\n}\n\nexport interface BasicAuthDescriptorConfig extends BasicAuthOptions {\n  /** Name identifier for this basic auth (default: property key) */\n  name?: string;\n  /** Path patterns to match (supports wildcards like /devtools/*) */\n  paths?: string[];\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class ServerBasicAuthProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly log = $logger();\n  protected readonly routerProvider = $inject(ServerRouterProvider);\n  protected readonly realm = \"Secure Area\";\n\n  /**\n   * Registered basic auth descriptors with their configurations\n   */\n  public readonly registeredAuths: BasicAuthDescriptorConfig[] = [];\n\n  /**\n   * Register a basic auth configuration (called by descriptors)\n   */\n  public registerAuth(config: BasicAuthDescriptorConfig): void {\n    this.registeredAuths.push(config);\n  }\n\n  public readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      for (const auth of this.registeredAuths) {\n        if (auth.paths) {\n          for (const pattern of auth.paths) {\n            const matchedRoutes = this.routerProvider.getRoutes(pattern);\n            for (const route of matchedRoutes) {\n              route.secure = {\n                basic: {\n                  username: auth.username,\n                  password: auth.password,\n                },\n              };\n            }\n          }\n        }\n      }\n\n      if (this.registeredAuths.length > 0) {\n        this.log.info(\n          `Initialized with ${this.registeredAuths.length} registered basic-auth configurations.`,\n        );\n      }\n    },\n  });\n\n  /**\n   * Hook into server:onRequest to check basic auth\n   */\n  public readonly onRequest = $hook({\n    on: \"server:onRequest\",\n    handler: async ({ route, request }) => {\n      const routeAuth = route.secure;\n      if (\n        typeof routeAuth === \"object\" &&\n        \"basic\" in routeAuth &&\n        routeAuth.basic\n      ) {\n        this.checkAuth(request, routeAuth.basic);\n      }\n    },\n  });\n\n  /**\n   * Hook into action:onRequest to check basic auth for actions\n   */\n  public readonly onActionRequest = $hook({\n    on: \"action:onRequest\",\n    handler: async ({ action, request }) => {\n      const routeAuth = action.route.secure;\n      if (isBasicAuth(routeAuth)) {\n        this.checkAuth(request, routeAuth.basic);\n      }\n    },\n  });\n\n  /**\n   * Check basic authentication\n   */\n  public checkAuth(request: ServerRequest, options: BasicAuthOptions): void {\n    const authHeader = request.headers?.authorization;\n\n    if (!authHeader || !authHeader.startsWith(\"Basic \")) {\n      this.sendAuthRequired(request);\n      throw new HttpError({\n        status: 401,\n        message: \"Authentication required\",\n      });\n    }\n\n    // decode base64 credentials\n    const base64Credentials = authHeader.slice(6); // Remove \"Basic \"\n    const credentials = Buffer.from(base64Credentials, \"base64\").toString(\n      \"utf-8\",\n    );\n\n    // split only on the first colon to handle passwords with colons\n    const colonIndex = credentials.indexOf(\":\");\n    const username =\n      colonIndex !== -1 ? credentials.slice(0, colonIndex) : credentials;\n    const password = colonIndex !== -1 ? credentials.slice(colonIndex + 1) : \"\";\n\n    // verify credentials using timing-safe comparison to prevent timing attacks\n    const isValid = this.timingSafeCredentialCheck(\n      username,\n      password,\n      options.username,\n      options.password,\n    );\n\n    if (!isValid) {\n      this.sendAuthRequired(request);\n      this.log.warn(`Failed basic auth attempt for user`, {\n        username,\n      });\n      throw new HttpError({\n        status: 401,\n        message: \"Invalid credentials\",\n      });\n    }\n  }\n\n  /**\n   * Performs a timing-safe comparison of credentials to prevent timing attacks.\n   * Always compares both username and password to avoid leaking which one is wrong.\n   */\n  protected timingSafeCredentialCheck(\n    inputUsername: string,\n    inputPassword: string,\n    expectedUsername: string,\n    expectedPassword: string,\n  ): boolean {\n    // Convert to buffers for timing-safe comparison\n    const inputUserBuf = Buffer.from(inputUsername, \"utf-8\");\n    const expectedUserBuf = Buffer.from(expectedUsername, \"utf-8\");\n    const inputPassBuf = Buffer.from(inputPassword, \"utf-8\");\n    const expectedPassBuf = Buffer.from(expectedPassword, \"utf-8\");\n\n    // timingSafeEqual requires same-length buffers\n    // When lengths differ, we compare against a dummy buffer to maintain constant time\n    const userMatch = this.safeCompare(inputUserBuf, expectedUserBuf);\n    const passMatch = this.safeCompare(inputPassBuf, expectedPassBuf);\n\n    // Both must match - bitwise AND avoids short-circuit evaluation\n    // eslint-disable-next-line no-bitwise\n    return (userMatch & passMatch) === 1;\n  }\n\n  /**\n   * Compares two buffers in constant time, handling different lengths safely.\n   * Returns 1 if equal, 0 if not equal.\n   */\n  protected safeCompare(input: Buffer, expected: Buffer): number {\n    // If lengths differ, compare input against itself to maintain timing\n    // but return 0 (not equal)\n    if (input.length !== expected.length) {\n      // Still perform a comparison to keep timing consistent\n      timingSafeEqual(input, input);\n      return 0;\n    }\n\n    return timingSafeEqual(input, expected) ? 1 : 0;\n  }\n\n  /**\n   * Send WWW-Authenticate header\n   */\n  protected sendAuthRequired(request: ServerRequest): void {\n    request.reply.setHeader(\"WWW-Authenticate\", `Basic realm=\"${this.realm}\"`);\n  }\n}\n\nexport const isBasicAuth = (\n  value: unknown,\n): value is { basic: BasicAuthOptions } => {\n  return (\n    typeof value === \"object\" && !!value && \"basic\" in value && !!value.basic\n  );\n};\n","import { $inject, createDescriptor, Descriptor, KIND } from \"alepha\";\nimport type { ServerRequest } from \"alepha/server\";\nimport type {\n  BasicAuthDescriptorConfig,\n  BasicAuthOptions,\n} from \"../providers/ServerBasicAuthProvider.ts\";\nimport { ServerBasicAuthProvider } from \"../providers/ServerBasicAuthProvider.ts\";\n\n/**\n * Declares HTTP Basic Authentication for server routes.\n * This descriptor provides methods to protect routes with username/password authentication.\n */\nexport const $basicAuth = (\n  options: BasicAuthDescriptorConfig,\n): AbstractBasicAuthDescriptor => {\n  return createDescriptor(BasicAuthDescriptor, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface AbstractBasicAuthDescriptor {\n  readonly name: string;\n  readonly options: BasicAuthDescriptorConfig;\n  check(request: ServerRequest, options?: BasicAuthOptions): void;\n}\n\nexport class BasicAuthDescriptor\n  extends Descriptor<BasicAuthDescriptorConfig>\n  implements AbstractBasicAuthDescriptor\n{\n  protected readonly serverBasicAuthProvider = $inject(ServerBasicAuthProvider);\n\n  public get name(): string {\n    return this.options.name ?? `${this.config.propertyKey}`;\n  }\n\n  protected onInit() {\n    // Register this auth configuration with the provider\n    this.serverBasicAuthProvider.registerAuth(this.options);\n  }\n\n  /**\n   * Checks basic auth for the given request using this descriptor's configuration.\n   */\n  public check(request: ServerRequest, options?: BasicAuthOptions): void {\n    const mergedOptions = { ...this.options, ...options };\n    this.serverBasicAuthProvider.checkAuth(request, mergedOptions);\n  }\n}\n\n$basicAuth[KIND] = BasicAuthDescriptor;\n","import { randomUUID } from \"node:crypto\";\nimport { $hook, $inject, Alepha } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  JwtProvider,\n  type Permission,\n  SecurityProvider,\n  type UserAccountToken,\n  userAccountInfoSchema,\n} from \"alepha/security\";\nimport {\n  $action,\n  ForbiddenError,\n  type ServerRequest,\n  UnauthorizedError,\n} from \"alepha/server\";\nimport {\n  type BasicAuthOptions,\n  isBasicAuth,\n} from \"./ServerBasicAuthProvider.ts\";\n\nexport class ServerSecurityProvider {\n  protected readonly log = $logger();\n  protected readonly securityProvider = $inject(SecurityProvider);\n  protected readonly jwtProvider = $inject(JwtProvider);\n  protected readonly alepha = $inject(Alepha);\n\n  protected readonly onConfigure = $hook({\n    on: \"configure\",\n    handler: async () => {\n      for (const action of this.alepha.descriptors($action)) {\n        // -------------------------------------------------------------------------------------------------------------\n        // if the action is disabled or not secure, we do NOT create a permission for it\n        // -------------------------------------------------------------------------------------------------------------\n        if (\n          action.options.disabled ||\n          action.options.secure === false ||\n          this.securityProvider.getRealms().length === 0\n        ) {\n          continue;\n        }\n\n        const secure = action.options.secure;\n        if (typeof secure !== \"object\") {\n          this.securityProvider.createPermission({\n            name: action.name,\n            group: action.group,\n            method: action.route.method,\n            path: action.route.path,\n          });\n        }\n      }\n    },\n  });\n\n  // -------------------------------------------------------------------------------------------------------------------\n\n  protected readonly onActionRequest = $hook({\n    on: \"action:onRequest\",\n    handler: async ({ action, request, options }) => {\n      // if you set explicitly secure: false, we assume you don't want any security check\n      // but only if no user is provided in options\n      if (action.options.secure === false && !options.user) {\n        this.log.trace(\"Skipping security check for route\");\n        return;\n      }\n\n      if (isBasicAuth(action.route.secure)) {\n        return;\n      }\n\n      const permission = this.securityProvider\n        .getPermissions()\n        .find(\n          (it) =>\n            it.path === action.route.path && it.method === action.route.method,\n        );\n\n      try {\n        request.user = this.createUserFromLocalFunctionContext(\n          options,\n          permission,\n        );\n\n        const route = action.route;\n        if (typeof route.secure === \"object\") {\n          this.check(request.user, route.secure);\n        }\n\n        this.alepha.state.set(\n          \"alepha.server.request.user\",\n          this.alepha.codec.decode(userAccountInfoSchema, request.user),\n        );\n      } catch (error) {\n        if (action.options.secure || permission) {\n          throw error;\n        }\n        // else, we skip the security check\n        this.log.trace(\"Skipping security check for action\");\n      }\n    },\n  });\n\n  protected readonly onRequest = $hook({\n    on: \"server:onRequest\",\n    priority: \"last\",\n    handler: async ({ request, route }) => {\n      // if you set explicitly secure: false, we assume you don't want any security check\n      if (route.secure === false) {\n        this.log.trace(\n          \"Skipping security check for route - explicitly disabled\",\n        );\n        return;\n      }\n\n      if (isBasicAuth(route.secure)) {\n        return;\n      }\n\n      const permission = this.securityProvider\n        .getPermissions()\n        .find((it) => it.path === route.path && it.method === route.method);\n\n      if (!request.headers.authorization && !route.secure && !permission) {\n        this.log.trace(\n          \"Skipping security check for route - no authorization header and not secure\",\n        );\n        return;\n      }\n\n      try {\n        // set user to request\n        request.user = await this.securityProvider.createUserFromToken(\n          request.headers.authorization,\n          { permission },\n        );\n\n        if (typeof route.secure === \"object\") {\n          this.check(request.user, route.secure);\n        }\n\n        this.alepha.state.set(\n          \"alepha.server.request.user\",\n          // remove sensitive info\n          this.alepha.codec.decode(userAccountInfoSchema, request.user),\n        );\n\n        this.log.trace(\"User set from request token\", {\n          user: request.user,\n          permission,\n        });\n      } catch (error) {\n        if (route.secure || permission) {\n          throw error;\n        }\n\n        // else, we skip the security check\n        this.log.trace(\n          \"Skipping security check for route - error occurred\",\n          error,\n        );\n      }\n    },\n  });\n\n  // -------------------------------------------------------------------------------------------------------------------\n\n  protected check(user: UserAccountToken, secure: ServerRouteSecure) {\n    if (secure.realm) {\n      if (user.realm !== secure.realm) {\n        throw new ForbiddenError(\n          `User must belong to realm '${secure.realm}' to access this route`,\n        );\n      }\n    }\n  }\n\n  /**\n   * Get the user account token for a local action call.\n   * There are three possible sources for the user:\n   * - `options.user`: the user passed in the options\n   * - `\"system\"`: the system user from the state (you MUST set state `server.security.system.user`)\n   * - `\"context\"`: the user from the request context (you MUST be in an HTTP request context)\n   *\n   * Priority order: `options.user` > `\"system\"` > `\"context\"`.\n   *\n   * In testing environment, if no user is provided, a test user is created based on the SecurityProvider's roles.\n   */\n  protected createUserFromLocalFunctionContext(\n    options: { user?: UserAccountToken | \"system\" | \"context\" },\n    permission?: Permission,\n  ): UserAccountToken {\n    const fromOptions =\n      typeof options.user === \"object\" ? options.user : undefined;\n\n    const type = typeof options.user === \"string\" ? options.user : undefined;\n\n    let user: UserAccountToken | undefined;\n\n    const fromContext = this.alepha.context.get<ServerRequest>(\"request\")?.user;\n    const fromSystem = this.alepha.state.get(\n      \"alepha.server.security.system.user\",\n    );\n\n    if (type === \"system\") {\n      user = fromSystem;\n    } else if (type === \"context\") {\n      user = fromContext;\n    } else {\n      user = fromOptions ?? fromContext ?? fromSystem;\n    }\n\n    if (!user) {\n      // in testing mode, we create a test user\n      if (this.alepha.isTest() && !(\"user\" in options)) {\n        return this.createTestUser();\n      }\n\n      throw new UnauthorizedError(\"User is required for calling this action\");\n    }\n\n    const roles =\n      user.roles ??\n      (this.alepha.isTest()\n        ? this.securityProvider.getRoles().map((role) => role.name)\n        : []);\n    let ownership: boolean | string | undefined;\n\n    if (permission) {\n      const result = this.securityProvider.checkPermission(\n        permission,\n        ...roles,\n      );\n      if (!result.isAuthorized) {\n        throw new ForbiddenError(\n          `Permission '${this.securityProvider.permissionToString(permission)}' is required for this route`,\n        );\n      }\n      ownership = result.ownership;\n    }\n\n    // create a new user object with ownership if needed\n    return {\n      ...user,\n      ownership,\n    };\n  }\n\n  // ---------------------------------------------------------------------------------------------------------------\n  // TESTING ONLY\n  // ---------------------------------------------------------------------------------------------------------------\n\n  protected createTestUser(): UserAccountToken {\n    return {\n      id: randomUUID(),\n      name: \"Test\",\n      roles: this.securityProvider.getRoles().map((role) => role.name),\n    };\n  }\n\n  protected readonly onClientRequest = $hook({\n    on: \"client:onRequest\",\n    handler: async ({ request, options }) => {\n      if (!this.alepha.isTest()) {\n        return;\n      }\n\n      // skip helper if user is explicitly set to undefined\n      if (\"user\" in options && options.user === undefined) {\n        return;\n      }\n\n      request.headers = new Headers(request.headers);\n\n      if (!request.headers.has(\"authorization\")) {\n        const test = this.createTestUser();\n        const user =\n          typeof options?.user === \"object\" ? options.user : undefined;\n        const sub = user?.id ?? test.id;\n        const roles = user?.roles ?? test.roles;\n\n        const token = await this.jwtProvider.create(\n          {\n            sub,\n            roles,\n          },\n          user?.realm ?? this.securityProvider.getRealms()[0]?.name,\n        );\n\n        request.headers.set(\"authorization\", `Bearer ${token}`);\n      }\n    },\n  });\n}\n\nexport type ServerRouteSecure = {\n  realm?: string;\n  basic?: BasicAuthOptions;\n};\n","import { $module } from \"alepha\";\nimport {\n  $permission,\n  $realm,\n  $role,\n  AlephaSecurity,\n  type UserAccount,\n  type UserAccountToken,\n} from \"alepha/security\";\nimport { AlephaServer, type FetchOptions } from \"alepha/server\";\nimport { $basicAuth } from \"./descriptors/$basicAuth.ts\";\nimport { ServerBasicAuthProvider } from \"./providers/ServerBasicAuthProvider.ts\";\nimport {\n  type ServerRouteSecure,\n  ServerSecurityProvider,\n} from \"./providers/ServerSecurityProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./descriptors/$basicAuth.ts\";\nexport * from \"./providers/ServerBasicAuthProvider.ts\";\nexport * from \"./providers/ServerSecurityProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha\" {\n  interface State {\n    /**\n     * Real (or fake) user account, used for internal actions.\n     *\n     * If you define this, you assume that all actions are executed by this user by default.\n     * > To force a different user, you need to pass it explicitly in the options.\n     */\n\n    \"alepha.server.security.system.user\"?: UserAccountToken;\n\n    /**\n     * The authenticated user account attached to the server request state.\n     *\n     * @internal\n     */\n    \"alepha.server.request.user\"?: UserAccount;\n  }\n}\n\ndeclare module \"alepha/server\" {\n  interface ServerRequest<TConfig> {\n    user?: UserAccountToken; // for all routes, user is maybe present\n  }\n\n  interface ServerActionRequest<TConfig> {\n    user: UserAccountToken; // for actions, user is always present\n  }\n\n  interface ServerRoute {\n    /**\n     * If true, the route will be protected by the security provider.\n     * All actions are secure by default, but you can disable it for specific actions.\n     */\n    secure?: boolean | ServerRouteSecure;\n  }\n\n  interface ClientRequestOptions extends FetchOptions {\n    /**\n     * Forward user from the previous request.\n     * If \"system\", use system user. @see {ServerSecurityProvider.localSystemUser}\n     * If \"context\", use the user from the current context (e.g. request).\n     *\n     * @default \"system\" if provided, else \"context\" if available.\n     */\n    user?: UserAccountToken | \"system\" | \"context\";\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha Server that provides security features. Based on the Alepha Security module.\n *\n * By default, all $action will be guarded by a permission check.\n *\n * @see {@link ServerSecurityProvider}\n * @module alepha.server.security\n */\nexport const AlephaServerSecurity = $module({\n  name: \"alepha.server.security\",\n  descriptors: [$realm, $role, $permission, $basicAuth],\n  services: [\n    AlephaServer,\n    AlephaSecurity,\n    ServerSecurityProvider,\n    ServerBasicAuthProvider,\n  ],\n});\n","import type { BinaryLike } from \"node:crypto\";\nimport { createHash } from \"node:crypto\";\nimport { $hook, $inject, Alepha } from \"alepha\";\nimport { $cache, type CacheDescriptorOptions } from \"alepha/cache\";\nimport { DateTimeProvider, type DurationLike } from \"alepha/datetime\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  ActionDescriptor,\n  type RequestConfigSchema,\n  type ServerRequest,\n  type ServerRoute,\n} from \"alepha/server\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha/server\" {\n  interface ServerRoute {\n    /**\n     * Enable caching for this route.\n     * - If true: enables both store and etag\n     * - If object: fine-grained control over store, etag, and cache-control headers\n     *\n     * @default false\n     */\n    cache?: ServerRouteCache;\n  }\n\n  interface ActionDescriptor<TConfig extends RequestConfigSchema> {\n    invalidate: () => Promise<void>;\n  }\n}\n\nActionDescriptor.prototype.invalidate = async function (\n  this: ActionDescriptor<RequestConfigSchema>,\n) {\n  await this.alepha.inject(ServerCacheProvider).invalidate(this.route);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class ServerCacheProvider {\n  protected readonly log = $logger();\n  protected readonly alepha = $inject(Alepha);\n  protected readonly time = $inject(DateTimeProvider);\n  protected readonly cache = $cache<RouteCacheEntry>({\n    provider: \"memory\",\n  });\n\n  public generateETag(content: BinaryLike): string {\n    return `\"${createHash(\"md5\").update(content).digest(\"hex\")}\"`;\n  }\n\n  public async invalidate(route: ServerRoute) {\n    const cache = route.cache;\n    if (!cache) {\n      return;\n    }\n\n    await this.cache.invalidate(this.createCacheKey(route));\n  }\n\n  protected readonly onActionRequest = $hook({\n    on: \"action:onRequest\",\n    handler: async ({ action, request }) => {\n      const cache = action.route.cache;\n\n      const shouldStore = this.shouldStore(cache);\n\n      // Only check cache if storing is enabled\n      if (shouldStore) {\n        const key = this.createCacheKey(action.route, request);\n        const cached = await this.cache.get(key);\n\n        if (cached) {\n          const body =\n            cached.contentType === \"application/json\"\n              ? JSON.parse(cached.body)\n              : cached.body;\n\n          this.log.trace(\"Cache hit for action\", {\n            key,\n            action: action.name,\n          });\n\n          request.reply.body = body; // just re-use, full trust\n        } else {\n          this.log.trace(\"Cache miss for action\", {\n            key,\n            action: action.name,\n          });\n        }\n      }\n    },\n  });\n\n  protected readonly onActionResponse = $hook({\n    on: \"action:onResponse\",\n    handler: async ({ action, request, response }) => {\n      const cache = action.route.cache;\n\n      const shouldStore = this.shouldStore(cache);\n\n      if (!shouldStore || !response) {\n        return;\n      }\n\n      // Don't cache error responses (status >= 400)\n      if (request.reply.status && request.reply.status >= 400) {\n        return;\n      }\n\n      // TODO: serialize the response body, exactly like in the server response hook\n      // this is bad\n      const contentType =\n        typeof response === \"string\" ? \"text/plain\" : \"application/json\";\n      const body =\n        contentType === \"text/plain\" ? response : JSON.stringify(response);\n\n      const generatedEtag = this.generateETag(body);\n      const lastModified = this.time.toISOString();\n\n      // Store response for cached actions\n      const key = this.createCacheKey(action.route, request);\n\n      this.log.trace(\"Storing response\", {\n        key,\n        action: action.name,\n      });\n\n      await this.cache.set(key, {\n        body: body,\n        lastModified,\n        contentType: contentType,\n        hash: generatedEtag,\n      });\n\n      // Set Cache-Control header if configured (for HTTP responses)\n      const cacheControl = this.buildCacheControlHeader(cache);\n      if (cacheControl) {\n        request.reply.setHeader(\"cache-control\", cacheControl);\n      }\n    },\n  });\n\n  protected readonly onRequest = $hook({\n    on: \"server:onRequest\",\n    handler: async ({ route, request }) => {\n      const cache = route.cache;\n\n      const shouldStore = this.shouldStore(cache);\n      const shouldUseEtag = this.shouldUseEtag(cache);\n\n      // Check for cached response or ETag\n      if (!shouldStore && !shouldUseEtag) {\n        return;\n      }\n\n      const key = this.createCacheKey(route, request);\n      const cached = await this.cache.get(key);\n\n      if (cached) {\n        // Check if client has matching ETag - return 304 for both cached and etag-only routes\n        if (\n          request.headers[\"if-none-match\"] === cached.hash ||\n          request.headers[\"if-modified-since\"] === cached.lastModified\n        ) {\n          request.reply.status = 304;\n          request.reply.setHeader(\"etag\", cached.hash);\n          request.reply.setHeader(\"last-modified\", cached.lastModified);\n          this.log.trace(\"ETag match, returning 304\", {\n            route: route.path,\n            etag: cached.hash,\n          });\n          return;\n        }\n\n        // Only serve cached content if storing is enabled (not for etag-only routes)\n        if (shouldStore) {\n          this.log.trace(\"Cache hit for route\", {\n            key,\n            route: route.path,\n          });\n\n          // if the cache is found, we can skip the request processing\n          // and return the cached response\n          request.reply.body = cached.body;\n          request.reply.status = cached.status ?? 200;\n\n          if (cached.contentType) {\n            request.reply.setHeader(\"Content-Type\", cached.contentType);\n          }\n\n          request.reply.setHeader(\"etag\", cached.hash);\n          request.reply.setHeader(\"last-modified\", cached.lastModified);\n        }\n      } else if (shouldStore) {\n        this.log.trace(\"Cache miss for route\", {\n          key,\n          route: route.path,\n        });\n      }\n    },\n  });\n\n  protected readonly onSend = $hook({\n    on: \"server:onSend\",\n    handler: async ({ route, request }) => {\n      // before sending the response, check if the ETag matches\n      // and if so, return a 304 Not Modified response\n      // -> this is only relevant for etag-only routes, not cached routes <-\n      const cache = route.cache;\n\n      const shouldStore = this.shouldStore(cache);\n      const shouldUseEtag = this.shouldUseEtag(cache);\n\n      if (request.reply.headers.etag) {\n        // ETag already set, skip\n        return;\n      }\n\n      if (\n        !shouldStore &&\n        shouldUseEtag &&\n        request.reply.body != null &&\n        (typeof request.reply.body === \"string\" ||\n          Buffer.isBuffer(request.reply.body))\n      ) {\n        const generatedEtag = this.generateETag(request.reply.body);\n\n        if (request.headers[\"if-none-match\"] === generatedEtag) {\n          request.reply.status = 304;\n          request.reply.body = undefined;\n          request.reply.setHeader(\"etag\", generatedEtag);\n          this.log.trace(\"ETag match on send, returning 304\", {\n            route: route.path,\n            etag: generatedEtag,\n          });\n          return;\n        }\n      }\n    },\n  });\n\n  protected readonly onResponse = $hook({\n    on: \"server:onResponse\",\n    priority: \"first\",\n    handler: async ({ route, request, response }) => {\n      const cache = route.cache;\n\n      // Set Cache-Control header if configured\n      const cacheControl = this.buildCacheControlHeader(cache);\n      if (cacheControl) {\n        response.headers[\"cache-control\"] = cacheControl;\n      }\n\n      const shouldStore = this.shouldStore(cache);\n      const shouldUseEtag = this.shouldUseEtag(cache);\n\n      // Skip if neither cache nor etag is enabled\n      if (!shouldStore && !shouldUseEtag) {\n        return;\n      }\n\n      // Only process string responses (text, html, json, etc.)\n      // Buffer is not supported by alepha/cache for now\n      if (typeof response.body !== \"string\") {\n        return;\n      }\n\n      // Don't cache error responses (status >= 400)\n      if (response.status && response.status >= 400) {\n        return;\n      }\n\n      const key = this.createCacheKey(route, request);\n      const generatedEtag = this.generateETag(response.body);\n      const lastModified = this.time.toISOString();\n\n      // Initialize headers if not present\n      response.headers ??= {};\n\n      // Store response if storing is enabled\n      if (shouldStore) {\n        this.log.trace(\"Storing response\", {\n          key,\n          route: route.path,\n          cache: !!cache,\n          etag: shouldUseEtag,\n        });\n\n        await this.cache.set(key, {\n          body: response.body,\n          status: response.status,\n          contentType: response.headers?.[\"content-type\"],\n          lastModified,\n          hash: generatedEtag,\n        });\n      }\n\n      // Set ETag headers if etag is enabled\n      if (shouldUseEtag) {\n        response.headers.etag = generatedEtag;\n        response.headers[\"last-modified\"] = lastModified;\n      }\n    },\n  });\n\n  public buildCacheControlHeader(cache?: ServerRouteCache): string | undefined {\n    if (!cache) {\n      return undefined;\n    }\n\n    // If cache is true or a DurationLike, no Cache-Control header is set\n    if (\n      cache === true ||\n      typeof cache === \"string\" ||\n      typeof cache === \"number\"\n    ) {\n      return undefined;\n    }\n\n    const control = cache.control;\n    if (!control) {\n      return undefined;\n    }\n\n    // If control is a string, return it directly\n    if (typeof control === \"string\") {\n      return control;\n    }\n\n    // If control is true, return default Cache-Control\n    if (control === true) {\n      return \"public, max-age=300\";\n    }\n\n    // Build Cache-Control from object directives\n    const directives: string[] = [];\n\n    if (control.public) {\n      directives.push(\"public\");\n    }\n    if (control.private) {\n      directives.push(\"private\");\n    }\n    if (control.noCache) {\n      directives.push(\"no-cache\");\n    }\n    if (control.noStore) {\n      directives.push(\"no-store\");\n    }\n    if (control.maxAge !== undefined) {\n      const maxAgeSeconds = this.durationToSeconds(control.maxAge);\n      directives.push(`max-age=${maxAgeSeconds}`);\n    }\n    if (control.sMaxAge !== undefined) {\n      const sMaxAgeSeconds = this.durationToSeconds(control.sMaxAge);\n      directives.push(`s-maxage=${sMaxAgeSeconds}`);\n    }\n    if (control.mustRevalidate) {\n      directives.push(\"must-revalidate\");\n    }\n    if (control.proxyRevalidate) {\n      directives.push(\"proxy-revalidate\");\n    }\n    if (control.immutable) {\n      directives.push(\"immutable\");\n    }\n\n    return directives.length > 0 ? directives.join(\", \") : undefined;\n  }\n\n  protected durationToSeconds(duration: number | DurationLike): number {\n    if (typeof duration === \"number\") {\n      return duration;\n    }\n\n    return this.time.duration(duration).asSeconds();\n  }\n\n  protected shouldStore(cache?: ServerRouteCache): boolean {\n    if (!cache) return false;\n    if (cache === true) return true;\n    if (typeof cache === \"object\" && cache.store) return true;\n    return false;\n  }\n\n  protected shouldUseEtag(cache?: ServerRouteCache): boolean {\n    // cache: true enables etag\n    if (cache === true) return true;\n    // Check object form\n    if (typeof cache === \"object\" && cache.etag) return true;\n    return false;\n  }\n\n  protected createCacheKey(route: ServerRoute, config?: ServerRequest): string {\n    const params: string[] = [];\n    for (const [key, value] of Object.entries(config?.params ?? {})) {\n      params.push(`${key}=${value}`);\n    }\n    for (const [key, value] of Object.entries(config?.query ?? {})) {\n      params.push(`${key}=${value}`);\n    }\n\n    return `${route.method}:${route.path.replaceAll(\":\", \"\")}:${params.join(\",\").replaceAll(\":\", \"\")}`;\n  }\n}\n\nexport type ServerRouteCache =\n  /**\n   * If true, enables caching with:\n   * - store: true\n   * - etag: true\n   */\n  | boolean\n  /**\n   * Object configuration for fine-grained cache control.\n   *\n   * If empty, no caching will be applied.\n   */\n  | {\n      /**\n       * If true, enables storing cached responses. (in-memory, Redis, @see alepha/cache for other providers)\n       * If a DurationLike is provided, it will be used as the TTL for the cache.\n       * If CacheDescriptorOptions is provided, it will be used to configure the cache storage.\n       *\n       * @default false\n       */\n      store?: true | DurationLike | CacheDescriptorOptions;\n      /**\n       * If true, enables ETag support for the cached responses.\n       */\n      etag?: true;\n      /**\n       * - If true, sets Cache-Control to \"public, max-age=300\" (5 minutes).\n       * - If string, sets Cache-Control to the provided value directly.\n       * - If object, configures Cache-Control directives.\n       */\n      control?: /**\n       * If true, sets Cache-Control to \"public, max-age=300\" (5 minutes).\n       */\n        | true\n        /**\n         * If string, sets Cache-Control to the provided value directly.\n         */\n        | string\n        /**\n         * If object, configures Cache-Control directives.\n         */\n        | {\n            /**\n             * Indicates that the response may be cached by any cache.\n             */\n            public?: boolean;\n            /**\n             * Indicates that the response is intended for a single user and must not be stored by a shared cache.\n             */\n            private?: boolean;\n            /**\n             * Forces caches to submit the request to the origin server for validation before releasing a cached copy.\n             */\n            noCache?: boolean;\n            /**\n             * Instructs caches not to store the response.\n             */\n            noStore?: boolean;\n            /**\n             * Maximum amount of time a resource is considered fresh.\n             * Can be specified as a number (seconds) or as a DurationLike object.\n             *\n             * @example 300 // 5 minutes in seconds\n             * @example { minutes: 5 } // 5 minutes\n             * @example { hours: 1 } // 1 hour\n             */\n            maxAge?: number | DurationLike;\n            /**\n             * Overrides max-age for shared caches (e.g., CDNs).\n             * Can be specified as a number (seconds) or as a DurationLike object.\n             */\n            sMaxAge?: number | DurationLike;\n            /**\n             * Indicates that once a resource becomes stale, caches must not use it without successful validation.\n             */\n            mustRevalidate?: boolean;\n            /**\n             * Similar to must-revalidate, but only for shared caches.\n             */\n            proxyRevalidate?: boolean;\n            /**\n             * Indicates that the response can be stored but must be revalidated before each use.\n             */\n            immutable?: boolean;\n          };\n    };\n\ninterface RouteCacheEntry {\n  contentType?: string;\n  body: any;\n  status?: number;\n  lastModified: string;\n  hash: string;\n}\n","import { $module } from \"alepha\";\nimport { AlephaCache } from \"alepha/cache\";\nimport { ServerCacheProvider } from \"./providers/ServerCacheProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./providers/ServerCacheProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha Server that provides server-side caching capabilities.\n * It uses the Alepha Cache module to cache responses from server actions ($action).\n * It also provides a ETag-based cache invalidation mechanism.\n *\n * @example\n * ```ts\n * import { Alepha } from \"alepha\";\n * import { $action } from \"alepha/server\";\n * import { AlephaServerCache } from \"alepha/server/cache\";\n *\n * class ApiServer {\n *   hello = $action({\n *     cache: true,\n *     handler: () => \"Hello, World!\",\n *   });\n * }\n *\n * const alepha = Alepha.create()\n *   .with(AlephaServerCache)\n *   .with(ApiServer);\n *\n * run(alepha);\n * ```\n *\n * @see {@link ServerCacheProvider}\n * @module alepha.server.cache\n */\nexport const AlephaServerCache = $module({\n  name: \"alepha.server.cache\",\n  services: [AlephaCache, ServerCacheProvider],\n});\n","import { createDescriptor, Descriptor, KIND } from \"alepha\";\nimport type { DurationLike } from \"alepha/datetime\";\n\n/**\n * Create a new static file handler.\n */\nexport const $serve = (\n  options: ServeDescriptorOptions = {},\n): ServeDescriptor => {\n  return createDescriptor(ServeDescriptor, options);\n};\n\nexport interface ServeDescriptorOptions {\n  /**\n   * Prefix for the served path.\n   *\n   * @default \"/\"\n   */\n  path?: string;\n\n  /**\n   * Path to the directory to serve.\n   *\n   * @default process.cwd()\n   */\n  root?: string;\n\n  /**\n   * If true, descriptor will be ignored.\n   *\n   * @default false\n   */\n  disabled?: boolean;\n\n  /**\n   * Whether to keep dot files (e.g. `.gitignore`, `.env`) in the served directory.\n   *\n   * @default true\n   */\n  ignoreDotEnvFiles?: boolean;\n\n  /**\n   * Whether to use the index.html file when the path is a directory.\n   *\n   * @default true\n   */\n  indexFallback?: boolean;\n\n  /**\n   * Force all requests \"not found\" to be served with the index.html file.\n   * This is useful for single-page applications (SPAs) that use client-side only routing.\n   */\n  historyApiFallback?: boolean;\n\n  /**\n   * Optional name of the descriptor.\n   * This is used for logging and debugging purposes.\n   *\n   * @default Key name.\n   */\n  name?: string;\n\n  /**\n   * Whether to use cache control headers.\n   *\n   * @default {}\n   */\n  cacheControl?: Partial<CacheControlOptions> | false;\n}\n\nexport interface CacheControlOptions {\n  /**\n   * Whether to use cache control headers.\n   *\n   * @default [.js, .css]\n   */\n  fileTypes: string[];\n\n  /**\n   * The maximum age of the cache in seconds.\n   *\n   * @default 60 * 60 * 24 * 2 // 2 days\n   */\n  maxAge: DurationLike;\n\n  /**\n   * Whether to use immutable cache control headers.\n   *\n   * @default true\n   */\n  immutable: boolean;\n}\n\nexport class ServeDescriptor extends Descriptor<ServeDescriptorOptions> {}\n\n$serve[KIND] = ServeDescriptor;\n","import { createReadStream } from \"node:fs\";\nimport { access, readdir, stat } from \"node:fs/promises\";\nimport { basename, isAbsolute, join } from \"node:path\";\nimport type { Readable as NodeStream } from \"node:stream\";\nimport { $hook, $inject, Alepha } from \"alepha\";\nimport { DateTimeProvider } from \"alepha/datetime\";\nimport { FileDetector } from \"alepha/file\";\nimport { $logger } from \"alepha/logger\";\nimport { type ServerHandler, ServerRouterProvider } from \"alepha/server\";\nimport { $serve, type ServeDescriptorOptions } from \"../descriptors/$serve.ts\";\n\nexport class ServerStaticProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly routerProvider = $inject(ServerRouterProvider);\n  protected readonly dateTimeProvider = $inject(DateTimeProvider);\n  protected readonly fileDetector = $inject(FileDetector);\n  protected readonly log = $logger();\n  protected readonly directories: ServeDirectory[] = [];\n\n  protected readonly configure = $hook({\n    on: \"configure\",\n    handler: async () => {\n      await Promise.all(\n        this.alepha\n          .descriptors($serve)\n          .map((it) => this.createStaticServer(it.options)),\n      );\n    },\n  });\n\n  public async createStaticServer(\n    options: ServeDescriptorOptions,\n  ): Promise<void> {\n    const prefix = options.path ?? \"/\";\n\n    let root = options.root ?? process.cwd();\n    if (!isAbsolute(root)) {\n      root = join(process.cwd(), root);\n    }\n\n    this.log.debug(\"Serve static files\", { prefix, root });\n\n    await stat(root);\n\n    // 1. get all files in the root directory (recursively)\n    const files = await this.getAllFiles(root, options.ignoreDotEnvFiles);\n\n    // 2. create a $route for each file (yes, this could be a lot of routes)\n    const routes = await Promise.all(\n      files.map(async (file) => {\n        const path = file.replace(root, \"\").replace(/\\\\/g, \"/\");\n        this.log.trace(`Mount ${join(prefix, path)} -> ${join(root, path)}`);\n        return {\n          path: join(prefix, encodeURI(path)),\n          handler: await this.createFileHandler(join(root, path), options),\n        };\n      }),\n    );\n\n    for (const route of routes) {\n      this.routerProvider.createRoute(route);\n\n      // if route is for index.html, also create a route without it\n      // e.g. /my/path/index.html -> /my/path/\n      if (\n        options.indexFallback !== false &&\n        route.path.endsWith(\"index.html\")\n      ) {\n        this.routerProvider.createRoute({\n          path: route.path.replace(/index\\.html$/, \"\"),\n          handler: route.handler,\n        });\n      }\n    }\n\n    // 3. store the directory info for reference\n    this.directories.push({\n      options,\n      files: files.map((file) => file.replace(root, \"\").replace(/\\\\/g, \"/\")),\n    });\n\n    // bonus! for SPAs, handle history API fallback\n    if (options.historyApiFallback) {\n      // meaning all unmatched routes should serve index.html\n      this.routerProvider.createRoute({\n        path: join(prefix, \"*\").replace(/\\\\/g, \"/\"),\n        handler: async (request) => {\n          const { reply } = request;\n\n          if (request.url.pathname.includes(\".\")) {\n            // If the request is for a file (e.g., /style.css), do not fall back\n            reply.headers[\"content-type\"] = \"text/plain\";\n            reply.body = \"Not Found\";\n            reply.status = 404;\n            return;\n          }\n\n          reply.headers[\"content-type\"] = \"text/html\";\n          reply.status = 200;\n\n          // Serve index.html for all unmatched routes\n          return createReadStream(join(root, \"index.html\"));\n        },\n      });\n    }\n  }\n\n  public async createFileHandler(\n    filepath: string,\n    options: ServeDescriptorOptions,\n  ): Promise<ServerHandler> {\n    const filename = basename(filepath);\n\n    const hasGzip = await access(`${filepath}.gz`)\n      .then(() => true)\n      .catch(() => false);\n\n    const hasBr = await access(`${filepath}.br`)\n      .then(() => true)\n      .catch(() => false);\n\n    const fileStat = await stat(filepath);\n    const lastModified = fileStat.mtime.toUTCString();\n    const etag = `\"${fileStat.size}-${fileStat.mtime.getTime()}\"`;\n    const contentType = this.fileDetector.getContentType(filename);\n    const cacheControl = this.getCacheControl(filename, options);\n\n    return async (request): Promise<NodeStream | undefined> => {\n      const { headers, reply } = request;\n      let path = filepath;\n\n      const encoding = headers[\"accept-encoding\"];\n      if (encoding) {\n        if (hasBr && encoding.includes(\"br\")) {\n          reply.headers[\"content-encoding\"] = \"br\";\n          path += \".br\";\n        } else if (hasGzip && encoding.includes(\"gzip\")) {\n          reply.headers[\"content-encoding\"] = \"gzip\";\n          path += \".gz\";\n        }\n      }\n\n      reply.headers[\"content-type\"] = contentType;\n      reply.headers[\"accept-ranges\"] = \"bytes\";\n      reply.headers[\"last-modified\"] = lastModified;\n\n      if (cacheControl) {\n        reply.headers[\"cache-control\"] =\n          `public, max-age=${cacheControl.maxAge}`;\n        if (cacheControl.immutable) {\n          reply.headers[\"cache-control\"] += \", immutable\";\n        }\n      }\n\n      reply.headers.etag = etag;\n      if (\n        headers[\"if-none-match\"] === etag ||\n        headers[\"if-modified-since\"] === lastModified\n      ) {\n        reply.status = 304;\n        return;\n      }\n\n      return createReadStream(path);\n    };\n  }\n\n  protected getCacheFileTypes(): string[] {\n    return [\n      \".js\",\n      \".css\",\n      \".woff\",\n      \".woff2\",\n      \".ttf\",\n      \".eot\",\n      \".otf\",\n      \".jpg\",\n      \".jpeg\",\n      \".png\",\n      \".svg\",\n      \".gif\",\n    ];\n  }\n\n  protected getCacheControl(\n    filename: string,\n    options: ServeDescriptorOptions,\n  ): { maxAge: number; immutable: boolean } | undefined {\n    if (!options.cacheControl) {\n      return;\n    }\n\n    const fileTypes =\n      options.cacheControl.fileTypes ?? this.getCacheFileTypes();\n\n    for (const type of fileTypes) {\n      if (filename.endsWith(type)) {\n        return {\n          immutable: options.cacheControl.immutable ?? true,\n          maxAge: this.dateTimeProvider\n            .duration(options.cacheControl.maxAge ?? [30, \"days\"])\n            .as(\"seconds\"),\n        };\n      }\n    }\n  }\n\n  public async getAllFiles(\n    dir: string,\n    ignoreDotEnvFiles = true,\n  ): Promise<string[]> {\n    const entries = await readdir(dir, { withFileTypes: true });\n\n    const files = await Promise.all(\n      entries.map((dirent) => {\n        // skip .env & other dot files\n        if (ignoreDotEnvFiles && dirent.name.startsWith(\".\")) {\n          return [];\n        }\n\n        const fullPath = join(dir, dirent.name);\n        return dirent.isDirectory() ? this.getAllFiles(fullPath) : fullPath;\n      }),\n    );\n\n    return files.flat();\n  }\n}\n\nexport interface ServeDirectory {\n  options: ServeDescriptorOptions;\n  files: string[];\n}\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\nimport { $serve } from \"./descriptors/$serve.ts\";\nimport { ServerStaticProvider } from \"./providers/ServerStaticProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./descriptors/$serve.ts\";\nexport * from \"./providers/ServerStaticProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Create static file server with `$static()`.\n *\n * @see {@link ServerStaticProvider}\n * @module alepha.server.static\n */\nexport const AlephaServerStatic = $module({\n  name: \"alepha.server.static\",\n  descriptors: [$serve],\n  services: [AlephaServer, ServerStaticProvider],\n});\n","import { createDescriptor, Descriptor, KIND } from \"alepha\";\n\n/**\n * Creates an OpenAPI/Swagger documentation descriptor with interactive UI.\n *\n * Automatically generates API documentation from your $action descriptors and serves\n * an interactive Swagger UI for testing endpoints. Supports customization, tag filtering,\n * and OAuth configuration.\n *\n * @example\n * ```ts\n * class App {\n *   docs = $swagger({\n *     prefix: \"/api-docs\",\n *     info: {\n *       title: \"My API\",\n *       version: \"1.0.0\",\n *       description: \"REST API documentation\"\n *     },\n *     excludeTags: [\"internal\"],\n *     ui: { root: \"/swagger\" }\n *   });\n * }\n * ```\n */\nexport const $swagger = (\n  options: SwaggerDescriptorOptions = {},\n): SwaggerDescriptor => {\n  return createDescriptor(SwaggerDescriptor, options);\n};\n\nexport interface SwaggerDescriptorOptions {\n  info?: OpenApiDocument[\"info\"];\n\n  /**\n   * @default: \"/docs\"\n   */\n  prefix?: string;\n\n  /**\n   * If true, docs will be disabled.\n   */\n  disabled?: boolean;\n\n  /**\n   * Tags to exclude from the documentation.\n   */\n  excludeTags?: string[];\n\n  /**\n   * Enable Swagger UI.\n   *\n   * @default true\n   */\n  ui?: boolean | SwaggerUiOptions;\n\n  /**\n   * Function to rewrite the OpenAPI document before serving it.\n   */\n  rewrite?: (doc: OpenApiDocument) => void;\n}\n\nexport interface SwaggerUiOptions {\n  root?: string;\n\n  initOAuth?: {\n    /**\n     * Default clientId.\n     */\n    clientId?: string;\n\n    /**\n     * realm query parameter (for oauth1) added to authorizationUrl and tokenUrl.\n     */\n    realm?: string;\n\n    /**\n     * application name, displayed in authorization popup.\n     */\n    appName?: string;\n\n    /**\n     * scope separator for passing scopes, encoded before calling, default\n     * value is a space (encoded value %20).\n     *\n     * @default ' '\n     */\n    scopeSeparator?: string;\n\n    /**\n     * string array or scope separator (i.e. space) separated string of\n     * initially selected oauth scopes\n     *\n     * @default []\n     */\n    scopes?: string | string[];\n\n    /**\n     * Additional query parameters added to authorizationUrl and tokenUrl.\n     * MUST be an object\n     */\n    additionalQueryStringParams?: { [key: string]: any };\n\n    /**\n     * Only activated for the accessCode flow. During the authorization_code\n     * request to the tokenUrl, pass the Client Password using the HTTP Basic\n     * Authentication scheme (Authorization header with Basic\n     * base64encode(client_id + client_secret)).\n     *\n     * @default false\n     */\n    useBasicAuthenticationWithAccessCodeGrant?: boolean;\n\n    /**\n     * Only applies to Authorization Code flows. Proof Key for Code Exchange\n     * brings enhanced security for OAuth public clients.\n     *\n     * @default false\n     */\n    usePkceWithAuthorizationCodeGrant?: boolean;\n  };\n}\n\nexport class SwaggerDescriptor extends Descriptor<SwaggerDescriptorOptions> {}\n\n$swagger[KIND] = SwaggerDescriptor;\n\nexport interface OpenApiDocument {\n  openapi: string;\n  info: {\n    title: string;\n    version: string;\n    description?: string;\n  };\n  paths: Record<string, any>;\n  components?: {\n    schemas?: Record<string, any>;\n    securitySchemes?: Record<string, any>;\n  };\n}\n\nexport interface OpenApiOperation {\n  tags?: string[];\n  summary?: string;\n  description?: string;\n  operationId?: string;\n  parameters?: Array<{\n    name: string;\n    in: \"query\" | \"header\" | \"path\" | \"cookie\";\n    description?: string;\n    required?: boolean;\n    schema: any;\n  }>;\n  requestBody?: {\n    description?: string;\n    content: Record<\n      string,\n      {\n        schema: any;\n      }\n    >;\n    required?: boolean;\n  };\n  responses: Record<\n    string,\n    {\n      description: string;\n      content?: Record<\n        string,\n        {\n          schema: any;\n        }\n      >;\n    }\n  >;\n  security?: Array<Record<string, any[]>>;\n}\n","import { join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport {\n  $atom,\n  $hook,\n  $inject,\n  $use,\n  Alepha,\n  isTypeFile,\n  type Static,\n  type TObject,\n  type TSchema,\n  t,\n} from \"alepha\";\nimport { FileSystemProvider } from \"alepha/file\";\nimport { $logger } from \"alepha/logger\";\nimport { AlephaSecurity } from \"alepha/security\";\nimport {\n  $action,\n  type ActionDescriptor,\n  type RequestConfigSchema,\n  ServerProvider,\n  ServerRouterProvider,\n} from \"alepha/server\";\nimport { ServerStaticProvider } from \"alepha/server/static\";\nimport {\n  $swagger,\n  type OpenApiDocument,\n  type OpenApiOperation,\n  type SwaggerDescriptorOptions,\n} from \"../descriptors/$swagger.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Swagger provider configuration atom\n */\nexport const swaggerOptions = $atom({\n  name: \"alepha.server.swagger.options\",\n  schema: t.object({\n    excludeKeys: t.optional(\n      t.array(t.string(), {\n        description: \"Keys to exclude from swagger schema\",\n      }),\n    ),\n  }),\n  default: {\n    excludeKeys: [],\n  },\n});\n\nexport type ServerSwaggerProviderOptions = Static<typeof swaggerOptions.schema>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [swaggerOptions.key]: ServerSwaggerProviderOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class ServerSwaggerProvider {\n  protected readonly serverStaticProvider = $inject(ServerStaticProvider);\n  protected readonly serverRouterProvider = $inject(ServerRouterProvider);\n  protected readonly serverProvider = $inject(ServerProvider);\n  protected readonly alepha = $inject(Alepha);\n  protected readonly log = $logger();\n  protected readonly options = $use(swaggerOptions);\n  protected readonly fs = $inject(FileSystemProvider);\n\n  public json?: OpenApiDocument;\n\n  protected readonly configure = $hook({\n    on: \"configure\",\n    priority: \"last\", // wait for all configurations, sometimes some actions are registered late!\n    handler: async (alepha) => {\n      const options = alepha.descriptors($swagger)?.[0]?.options;\n      if (!options) {\n        return;\n      }\n\n      this.json = await this.createSwagger(options);\n    },\n  });\n\n  public async createSwagger(\n    options: SwaggerDescriptorOptions,\n  ): Promise<OpenApiDocument | undefined> {\n    if (options.disabled) {\n      return;\n    }\n\n    const json = this.configureOpenApi(\n      this.alepha.descriptors($action),\n      options,\n    );\n\n    if (options.rewrite) {\n      options.rewrite(json);\n    }\n\n    const prefix = options.prefix ?? \"/docs\";\n\n    this.configureSwaggerApi(prefix, json);\n\n    if (options.ui !== false) {\n      await this.configureSwaggerUi(prefix, options);\n    }\n\n    return json;\n  }\n\n  protected configureOpenApi(\n    actions: ActionDescriptor<RequestConfigSchema>[],\n    doc: SwaggerDescriptorOptions,\n  ): OpenApiDocument {\n    const openApi: OpenApiDocument = {\n      openapi: \"3.0.0\",\n      info: doc.info ?? {\n        title: \"API Documentation\",\n        version: \"1.0.0\",\n      },\n      paths: {},\n      components: {},\n    };\n\n    const hasSecurity = this.alepha.has(AlephaSecurity);\n    if (hasSecurity && openApi.components) {\n      openApi.components.securitySchemes = {\n        bearerAuth: {\n          type: \"http\",\n          scheme: \"bearer\",\n          bearerFormat: \"JWT\",\n        },\n      };\n    }\n\n    const excludeTags = doc.excludeTags ?? [];\n    const schemas: Record<string, any> = {};\n\n    const schema = (source: TSchema) => {\n      if (\"title\" in source && typeof source.title === \"string\") {\n        schemas[source.title] = copy(source);\n        return { $ref: `#/components/schemas/${source.title}` };\n      }\n      return copy(source);\n    };\n\n    const copy = (obj: any) => {\n      const newValue = JSON.parse(JSON.stringify(obj));\n      this.removePrivateFields(newValue, [\n        ...(this.options.excludeKeys || []),\n        \"~options\",\n      ]);\n      return newValue;\n    };\n\n    for (const route of actions) {\n      if (!route.options.schema) {\n        continue;\n      }\n\n      const response = this.getResponseSchema(route);\n      if (!response) {\n        continue;\n      }\n\n      if (excludeTags.includes(route.group)) {\n        continue;\n      }\n\n      if (route.options.hide) {\n        continue;\n      }\n\n      const operation: OpenApiOperation = {\n        operationId: route.name,\n        summary: route.options.summary,\n        description: route.options.description,\n        tags: [route.group.replaceAll(\":\", \" / \")],\n        responses: {\n          [response.status]: {\n            description: \"\",\n            content: response.type\n              ? {\n                  [response.type]: {\n                    schema: schema(response.schema),\n                  },\n                }\n              : undefined,\n          },\n        },\n      };\n\n      if (route.options.secure !== false && hasSecurity) {\n        operation.security = [{ bearerAuth: [] }];\n      }\n\n      const g = t.raw;\n\n      if (\n        g.IsObject(route.options.schema.body) ||\n        g.IsArray(route.options.schema.body)\n      ) {\n        if (\n          g.IsObject(route.options.schema.body) &&\n          this.isBodyMultipart(route.options.schema.body)\n        ) {\n          operation.requestBody = {\n            required: true,\n            content: {\n              \"multipart/form-data\": {\n                schema: schema(route.options.schema.body),\n              },\n            },\n          };\n        } else {\n          operation.requestBody = {\n            required: true,\n            content: {\n              \"application/json\": {\n                schema: schema(route.options.schema.body),\n              },\n            },\n          };\n        }\n      }\n\n      if (g.IsObject(route.options.schema.query)) {\n        operation.parameters ??= [];\n        for (const [key, value] of Object.entries(\n          route.options.schema.query.properties,\n        )) {\n          operation.parameters.push({\n            name: key,\n            in: \"query\",\n            required: false,\n            schema: schema(value),\n          });\n        }\n      }\n\n      if (g.IsObject(route.options.schema.params)) {\n        operation.parameters ??= [];\n        for (const [key, value] of Object.entries(\n          route.options.schema.params.properties,\n        )) {\n          const description =\n            \"description\" in value && typeof value.description === \"string\"\n              ? value.description\n              : undefined;\n          const ref = schema(value);\n          delete ref.description;\n          operation.parameters.push({\n            name: key,\n            in: \"path\",\n            required: true,\n            description,\n            schema: ref,\n          });\n        }\n      }\n\n      const url = route.prefix + this.replacePathParams(route.path);\n\n      openApi.paths[url] = {\n        ...openApi.paths[url],\n        [route.method.toLowerCase()]: operation,\n      };\n    }\n\n    if (openApi.components) openApi.components.schemas = schemas;\n\n    return JSON.parse(JSON.stringify(openApi));\n  }\n\n  public isBodyMultipart(schema: TObject): boolean {\n    for (const key in schema.properties) {\n      if (isTypeFile(schema.properties[key])) {\n        return true;\n      }\n    }\n    return false;\n  }\n\n  public replacePathParams(url: string): string {\n    return url.replace(/:\\w+/g, (match) => {\n      const paramName = match.slice(1);\n      return `{${paramName}}`;\n    });\n  }\n\n  public getResponseSchema(route: ActionDescriptor<RequestConfigSchema>):\n    | {\n        type?: string;\n        schema?: any;\n        status: number;\n      }\n    | undefined {\n    const schema: any = route.options.schema?.response;\n    if (!schema) {\n      return {\n        status: 204,\n      };\n    }\n\n    if (t.schema.isObject(schema) || t.schema.isArray(schema)) {\n      return {\n        schema,\n        status: 200,\n        type: \"application/json\",\n      };\n    }\n\n    if (t.schema.isString(schema)) {\n      return {\n        schema,\n        status: 200,\n        type: \"text/plain\",\n      };\n    }\n\n    if (isTypeFile(schema)) {\n      return {\n        schema,\n        status: 200,\n        type: \"application/octet-stream\",\n      };\n    }\n\n    const status = Object.keys(schema)[0];\n    if (t.schema.isObject(schema[status]) || isTypeFile(schema[status])) {\n      return {\n        schema,\n        type: t.schema.isObject(schema[status])\n          ? \"application/json\"\n          : \"application/octet-stream\",\n        status: Number(status),\n      };\n    }\n  }\n\n  protected configureSwaggerApi(prefix: string, json: OpenApiDocument): void {\n    this.serverRouterProvider.createRoute({\n      method: \"GET\",\n      path: `${prefix}/json`,\n      cache: {\n        etag: true,\n      },\n      schema: {\n        response: t.json(),\n      },\n      handler: () => json,\n    });\n    this.log.info(`Swagger API available at ${prefix}/json`);\n  }\n\n  protected async configureSwaggerUi(\n    prefix: string,\n    options: SwaggerDescriptorOptions,\n  ): Promise<void> {\n    const ui = typeof options.ui === \"object\" ? options.ui : {};\n    const initializer = `\nwindow.onload = function() {\n\twindow.ui = SwaggerUIBundle({\n\t\turl: \"/docs/json\",\n\t\tdom_id: '#swagger-ui',\n\t\tdeepLinking: true,\n\t\tpresets: [\n\t\t\tSwaggerUIBundle.presets.apis,\n\t\t\tSwaggerUIStandalonePreset\n\t\t],\n\t\tplugins: [\n\t\t\tSwaggerUIBundle.plugins.DownloadUrl\n\t\t],\n\t\tlayout: \"BaseLayout\"\n\t});\n\n  document.body.style.backgroundColor = \"#f2f2f2\";\n\n\tconst options = ${JSON.stringify(ui)};\n\n\tif (options.initOAuth) {\n\t\tui.initOAuth(options.initOAuth);\n\t}\n};\n\t\t`.trim();\n\n    const dirname = fileURLToPath(import.meta.url);\n\n    const root = await this.getAssetPath(\n      ui.root,\n      join(dirname, \"../../assets/swagger-ui\"),\n      join(dirname, \"../../../../assets/swagger-ui\"),\n    );\n\n    if (!root) {\n      this.log.warn(`Failed to locate Swagger UI assets for path ${prefix}`);\n      return;\n    }\n\n    await this.serverStaticProvider.createStaticServer({\n      path: prefix,\n      root,\n    });\n\n    this.serverRouterProvider.createRoute({\n      method: \"GET\",\n      path: `${prefix}/swagger-initializer.js`,\n      cache: {\n        etag: true,\n      },\n      handler: ({ reply }) => {\n        reply.headers[\"content-type\"] = \"application/javascript; charset=utf-8\";\n        return initializer;\n      },\n    });\n\n    this.log.info(\n      `Swagger UI available at ${this.serverProvider.hostname}${prefix}/`,\n    );\n  }\n\n  protected async getAssetPath(\n    ...paths: (string | undefined)[]\n  ): Promise<string | undefined> {\n    for (const path of paths) {\n      if (!path) continue;\n      const exists = await this.fs.exists(path);\n      if (exists) {\n        return path;\n      }\n    }\n  }\n\n  public removePrivateFields<T extends Record<string, any>>(\n    obj: T,\n    excludeList: string[],\n  ): T {\n    if (obj === null || typeof obj !== \"object\") return obj;\n\n    const visited = new WeakSet();\n\n    const traverse = (o: any): void => {\n      if (visited.has(o)) return;\n      visited.add(o);\n\n      if (Array.isArray(o)) {\n        for (let i = 0; i < o.length; i++) {\n          const item = o[i];\n          if (item !== null && typeof item === \"object\") {\n            traverse(item);\n          }\n        }\n      } else {\n        for (const excludeKey of excludeList) {\n          if (excludeKey in o) {\n            delete o[excludeKey];\n          }\n        }\n        for (const key in o) {\n          const item = o[key];\n          if (item !== null && typeof item === \"object\") {\n            traverse(item);\n          }\n        }\n      }\n    };\n\n    traverse(obj);\n    return obj;\n  }\n}\n","import \"alepha/server/security\";\nimport { $module } from \"alepha\";\nimport { AlephaServer, type RequestConfigSchema } from \"alepha/server\";\nimport { AlephaServerCache } from \"alepha/server/cache\";\nimport { AlephaServerStatic } from \"alepha/server/static\";\nimport { $swagger } from \"./descriptors/$swagger.ts\";\nimport { ServerSwaggerProvider } from \"./providers/ServerSwaggerProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./descriptors/$swagger.ts\";\nexport * from \"./providers/ServerSwaggerProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha/server\" {\n  interface ActionDescriptorOptions<TConfig extends RequestConfigSchema> {\n    /**\n     * Short description of the route.\n     */\n    summary?: string;\n\n    /**\n     * Don't include this action in the Swagger documentation.\n     */\n    hide?: boolean;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha Server that provides Swagger documentation capabilities.\n * It generates OpenAPI v3 documentation for the server's endpoints ($action).\n * It also provides a Swagger UI for interactive API documentation.\n *\n * @see {@link ServerSwaggerProvider}\n * @module alepha.server.swagger\n */\nexport const AlephaServerSwagger = $module({\n  name: \"alepha.server.swagger\",\n  descriptors: [$swagger],\n  services: [ServerSwaggerProvider],\n  register: (alepha) => {\n    alepha.with(AlephaServer);\n    alepha.with(AlephaServerCache);\n    alepha.with(AlephaServerStatic);\n    alepha.with(ServerSwaggerProvider);\n    alepha.state.push(\"alepha.build.assets\", \"alepha\");\n  },\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["openApi: OpenApiDocument","schemas: Record<string, any>","operation: OpenApiOperation","schema: any"],"sources":["../../src/server-swagger/primitives/$swagger.ts","../../src/server-swagger/providers/ServerSwaggerProvider.ts","../../src/server-swagger/index.ts"],"sourcesContent":["import { createPrimitive, KIND, Primitive } from \"alepha\";\n\n/**\n * Creates an OpenAPI/Swagger documentation primitive with interactive UI.\n *\n * Automatically generates API documentation from your $action primitives and serves\n * an interactive Swagger UI for testing endpoints. Supports customization, tag filtering,\n * and OAuth configuration.\n *\n * @example\n * ```ts\n * class App {\n *   docs = $swagger({\n *     prefix: \"/api-docs\",\n *     info: {\n *       title: \"My API\",\n *       version: \"1.0.0\",\n *       description: \"REST API documentation\"\n *     },\n *     excludeTags: [\"internal\"],\n *     ui: { root: \"/swagger\" }\n *   });\n * }\n * ```\n */\nexport const $swagger = (\n  options: SwaggerPrimitiveOptions = {},\n): SwaggerPrimitive => {\n  return createPrimitive(SwaggerPrimitive, options);\n};\n\nexport interface SwaggerPrimitiveOptions {\n  info?: OpenApiDocument[\"info\"];\n\n  /**\n   * @default: \"/docs\"\n   */\n  prefix?: string;\n\n  /**\n   * If true, docs will be disabled.\n   */\n  disabled?: boolean;\n\n  /**\n   * Tags to exclude from the documentation.\n   */\n  excludeTags?: string[];\n\n  /**\n   * Enable Swagger UI.\n   *\n   * @default true\n   */\n  ui?: boolean | SwaggerUiOptions;\n\n  /**\n   * Function to rewrite the OpenAPI document before serving it.\n   */\n  rewrite?: (doc: OpenApiDocument) => void;\n}\n\nexport interface SwaggerUiOptions {\n  root?: string;\n\n  initOAuth?: {\n    /**\n     * Default clientId.\n     */\n    clientId?: string;\n\n    /**\n     * realm query parameter (for oauth1) added to authorizationUrl and tokenUrl.\n     */\n    realm?: string;\n\n    /**\n     * application name, displayed in authorization popup.\n     */\n    appName?: string;\n\n    /**\n     * scope separator for passing scopes, encoded before calling, default\n     * value is a space (encoded value %20).\n     *\n     * @default ' '\n     */\n    scopeSeparator?: string;\n\n    /**\n     * string array or scope separator (i.e. space) separated string of\n     * initially selected oauth scopes\n     *\n     * @default []\n     */\n    scopes?: string | string[];\n\n    /**\n     * Additional query parameters added to authorizationUrl and tokenUrl.\n     * MUST be an object\n     */\n    additionalQueryStringParams?: { [key: string]: any };\n\n    /**\n     * Only activated for the accessCode flow. During the authorization_code\n     * request to the tokenUrl, pass the Client Password using the HTTP Basic\n     * Authentication scheme (Authorization header with Basic\n     * base64encode(client_id + client_secret)).\n     *\n     * @default false\n     */\n    useBasicAuthenticationWithAccessCodeGrant?: boolean;\n\n    /**\n     * Only applies to Authorization Code flows. Proof Key for Code Exchange\n     * brings enhanced security for OAuth public clients.\n     *\n     * @default false\n     */\n    usePkceWithAuthorizationCodeGrant?: boolean;\n  };\n}\n\nexport class SwaggerPrimitive extends Primitive<SwaggerPrimitiveOptions> {}\n\n$swagger[KIND] = SwaggerPrimitive;\n\nexport interface OpenApiDocument {\n  openapi: string;\n  info: {\n    title: string;\n    version: string;\n    description?: string;\n  };\n  paths: Record<string, any>;\n  components?: {\n    schemas?: Record<string, any>;\n    securitySchemes?: Record<string, any>;\n  };\n}\n\nexport interface OpenApiOperation {\n  tags?: string[];\n  summary?: string;\n  description?: string;\n  operationId?: string;\n  parameters?: Array<{\n    name: string;\n    in: \"query\" | \"header\" | \"path\" | \"cookie\";\n    description?: string;\n    required?: boolean;\n    schema: any;\n  }>;\n  requestBody?: {\n    description?: string;\n    content: Record<\n      string,\n      {\n        schema: any;\n      }\n    >;\n    required?: boolean;\n  };\n  responses: Record<\n    string,\n    {\n      description: string;\n      content?: Record<\n        string,\n        {\n          schema: any;\n        }\n      >;\n    }\n  >;\n  security?: Array<Record<string, any[]>>;\n}\n","import { join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport {\n  $atom,\n  $hook,\n  $inject,\n  $use,\n  Alepha,\n  isTypeFile,\n  type Static,\n  type TObject,\n  type TSchema,\n  t,\n} from \"alepha\";\nimport { FileSystemProvider } from \"alepha/file\";\nimport { $logger } from \"alepha/logger\";\nimport { AlephaSecurity } from \"alepha/security\";\nimport {\n  $action,\n  type ActionPrimitive,\n  type RequestConfigSchema,\n  ServerProvider,\n  ServerRouterProvider,\n} from \"alepha/server\";\nimport { ServerStaticProvider } from \"alepha/server/static\";\nimport {\n  $swagger,\n  type OpenApiDocument,\n  type OpenApiOperation,\n  type SwaggerPrimitiveOptions,\n} from \"../primitives/$swagger.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Swagger provider configuration atom\n */\nexport const swaggerOptions = $atom({\n  name: \"alepha.server.swagger.options\",\n  schema: t.object({\n    excludeKeys: t.optional(\n      t.array(t.string(), {\n        description: \"Keys to exclude from swagger schema\",\n      }),\n    ),\n  }),\n  default: {\n    excludeKeys: [],\n  },\n});\n\nexport type ServerSwaggerProviderOptions = Static<typeof swaggerOptions.schema>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [swaggerOptions.key]: ServerSwaggerProviderOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class ServerSwaggerProvider {\n  protected readonly serverStaticProvider = $inject(ServerStaticProvider);\n  protected readonly serverRouterProvider = $inject(ServerRouterProvider);\n  protected readonly serverProvider = $inject(ServerProvider);\n  protected readonly alepha = $inject(Alepha);\n  protected readonly log = $logger();\n  protected readonly options = $use(swaggerOptions);\n  protected readonly fs = $inject(FileSystemProvider);\n\n  public json?: OpenApiDocument;\n\n  protected readonly configure = $hook({\n    on: \"configure\",\n    priority: \"last\", // wait for all configurations, sometimes some actions are registered late!\n    handler: async (alepha) => {\n      const options = alepha.primitives($swagger)?.[0]?.options;\n      if (!options) {\n        return;\n      }\n\n      this.json = await this.createSwagger(options);\n    },\n  });\n\n  public async createSwagger(\n    options: SwaggerPrimitiveOptions,\n  ): Promise<OpenApiDocument | undefined> {\n    if (options.disabled) {\n      return;\n    }\n\n    const json = this.configureOpenApi(\n      this.alepha.primitives($action),\n      options,\n    );\n\n    if (options.rewrite) {\n      options.rewrite(json);\n    }\n\n    const prefix = options.prefix ?? \"/docs\";\n\n    this.configureSwaggerApi(prefix, json);\n\n    if (options.ui !== false) {\n      await this.configureSwaggerUi(prefix, options);\n    }\n\n    return json;\n  }\n\n  protected configureOpenApi(\n    actions: ActionPrimitive<RequestConfigSchema>[],\n    doc: SwaggerPrimitiveOptions,\n  ): OpenApiDocument {\n    const openApi: OpenApiDocument = {\n      openapi: \"3.0.0\",\n      info: doc.info ?? {\n        title: \"API Documentation\",\n        version: \"1.0.0\",\n      },\n      paths: {},\n      components: {},\n    };\n\n    const hasSecurity = this.alepha.has(AlephaSecurity);\n    if (hasSecurity && openApi.components) {\n      openApi.components.securitySchemes = {\n        bearerAuth: {\n          type: \"http\",\n          scheme: \"bearer\",\n          bearerFormat: \"JWT\",\n        },\n      };\n    }\n\n    const excludeTags = doc.excludeTags ?? [];\n    const schemas: Record<string, any> = {};\n\n    const schema = (source: TSchema) => {\n      if (\"title\" in source && typeof source.title === \"string\") {\n        schemas[source.title] = copy(source);\n        return { $ref: `#/components/schemas/${source.title}` };\n      }\n      return copy(source);\n    };\n\n    const copy = (obj: any) => {\n      const newValue = JSON.parse(JSON.stringify(obj));\n      this.removePrivateFields(newValue, [\n        ...(this.options.excludeKeys || []),\n        \"~options\",\n      ]);\n      return newValue;\n    };\n\n    for (const route of actions) {\n      if (!route.options.schema) {\n        continue;\n      }\n\n      const response = this.getResponseSchema(route);\n      if (!response) {\n        continue;\n      }\n\n      if (excludeTags.includes(route.group)) {\n        continue;\n      }\n\n      if (route.options.hide) {\n        continue;\n      }\n\n      const operation: OpenApiOperation = {\n        operationId: route.name,\n        summary: route.options.summary,\n        description: route.options.description,\n        tags: [route.group.replaceAll(\":\", \" / \")],\n        responses: {\n          [response.status]: {\n            description: \"\",\n            content: response.type\n              ? {\n                  [response.type]: {\n                    schema: schema(response.schema),\n                  },\n                }\n              : undefined,\n          },\n        },\n      };\n\n      if (route.options.secure !== false && hasSecurity) {\n        operation.security = [{ bearerAuth: [] }];\n      }\n\n      const g = t.raw;\n\n      if (\n        g.IsObject(route.options.schema.body) ||\n        g.IsArray(route.options.schema.body)\n      ) {\n        if (\n          g.IsObject(route.options.schema.body) &&\n          this.isBodyMultipart(route.options.schema.body)\n        ) {\n          operation.requestBody = {\n            required: true,\n            content: {\n              \"multipart/form-data\": {\n                schema: schema(route.options.schema.body),\n              },\n            },\n          };\n        } else {\n          operation.requestBody = {\n            required: true,\n            content: {\n              \"application/json\": {\n                schema: schema(route.options.schema.body),\n              },\n            },\n          };\n        }\n      }\n\n      if (g.IsObject(route.options.schema.query)) {\n        operation.parameters ??= [];\n        for (const [key, value] of Object.entries(\n          route.options.schema.query.properties,\n        )) {\n          operation.parameters.push({\n            name: key,\n            in: \"query\",\n            required: false,\n            schema: schema(value),\n          });\n        }\n      }\n\n      if (g.IsObject(route.options.schema.params)) {\n        operation.parameters ??= [];\n        for (const [key, value] of Object.entries(\n          route.options.schema.params.properties,\n        )) {\n          const description =\n            \"description\" in value && typeof value.description === \"string\"\n              ? value.description\n              : undefined;\n          const ref = schema(value);\n          delete ref.description;\n          operation.parameters.push({\n            name: key,\n            in: \"path\",\n            required: true,\n            description,\n            schema: ref,\n          });\n        }\n      }\n\n      const url = route.prefix + this.replacePathParams(route.path);\n\n      openApi.paths[url] = {\n        ...openApi.paths[url],\n        [route.method.toLowerCase()]: operation,\n      };\n    }\n\n    if (openApi.components) openApi.components.schemas = schemas;\n\n    return JSON.parse(JSON.stringify(openApi));\n  }\n\n  public isBodyMultipart(schema: TObject): boolean {\n    for (const key in schema.properties) {\n      if (isTypeFile(schema.properties[key])) {\n        return true;\n      }\n    }\n    return false;\n  }\n\n  public replacePathParams(url: string): string {\n    return url.replace(/:\\w+/g, (match) => {\n      const paramName = match.slice(1);\n      return `{${paramName}}`;\n    });\n  }\n\n  public getResponseSchema(route: ActionPrimitive<RequestConfigSchema>):\n    | {\n        type?: string;\n        schema?: any;\n        status: number;\n      }\n    | undefined {\n    const schema: any = route.options.schema?.response;\n    if (!schema) {\n      return {\n        status: 204,\n      };\n    }\n\n    if (t.schema.isObject(schema) || t.schema.isArray(schema)) {\n      return {\n        schema,\n        status: 200,\n        type: \"application/json\",\n      };\n    }\n\n    if (t.schema.isString(schema)) {\n      return {\n        schema,\n        status: 200,\n        type: \"text/plain\",\n      };\n    }\n\n    if (isTypeFile(schema)) {\n      return {\n        schema,\n        status: 200,\n        type: \"application/octet-stream\",\n      };\n    }\n\n    const status = Object.keys(schema)[0];\n    if (t.schema.isObject(schema[status]) || isTypeFile(schema[status])) {\n      return {\n        schema,\n        type: t.schema.isObject(schema[status])\n          ? \"application/json\"\n          : \"application/octet-stream\",\n        status: Number(status),\n      };\n    }\n  }\n\n  protected configureSwaggerApi(prefix: string, json: OpenApiDocument): void {\n    this.serverRouterProvider.createRoute({\n      method: \"GET\",\n      path: `${prefix}/json`,\n      cache: {\n        etag: true,\n      },\n      schema: {\n        response: t.json(),\n      },\n      handler: () => json,\n    });\n    this.log.info(`Swagger API available at ${prefix}/json`);\n  }\n\n  protected async configureSwaggerUi(\n    prefix: string,\n    options: SwaggerPrimitiveOptions,\n  ): Promise<void> {\n    const ui = typeof options.ui === \"object\" ? options.ui : {};\n    const initializer = `\nwindow.onload = function() {\n\twindow.ui = SwaggerUIBundle({\n\t\turl: \"/docs/json\",\n\t\tdom_id: '#swagger-ui',\n\t\tdeepLinking: true,\n\t\tpresets: [\n\t\t\tSwaggerUIBundle.presets.apis,\n\t\t\tSwaggerUIStandalonePreset\n\t\t],\n\t\tplugins: [\n\t\t\tSwaggerUIBundle.plugins.DownloadUrl\n\t\t],\n\t\tlayout: \"BaseLayout\"\n\t});\n\n  document.body.style.backgroundColor = \"#f2f2f2\";\n\n\tconst options = ${JSON.stringify(ui)};\n\n\tif (options.initOAuth) {\n\t\tui.initOAuth(options.initOAuth);\n\t}\n};\n\t\t`.trim();\n\n    const dirname = fileURLToPath(import.meta.url);\n\n    const root = await this.getAssetPath(\n      ui.root,\n      join(dirname, \"../../assets/swagger-ui\"),\n      join(dirname, \"../../../assets/swagger-ui\"),\n      join(dirname, \"../../../../assets/swagger-ui\"),\n    );\n\n    if (!root) {\n      this.log.warn(`Failed to locate Swagger UI assets for path ${prefix}`);\n      return;\n    }\n\n    await this.serverStaticProvider.createStaticServer({\n      path: prefix,\n      root,\n    });\n\n    this.serverRouterProvider.createRoute({\n      method: \"GET\",\n      path: `${prefix}/swagger-initializer.js`,\n      cache: {\n        etag: true,\n      },\n      handler: ({ reply }) => {\n        reply.headers[\"content-type\"] = \"application/javascript; charset=utf-8\";\n        return initializer;\n      },\n    });\n\n    this.log.info(\n      `Swagger UI available at ${this.serverProvider.hostname}${prefix}/`,\n    );\n  }\n\n  protected async getAssetPath(\n    ...paths: (string | undefined)[]\n  ): Promise<string | undefined> {\n    for (const path of paths) {\n      if (!path) continue;\n      const exists = await this.fs.exists(path);\n      if (exists) {\n        return path;\n      }\n    }\n  }\n\n  public removePrivateFields<T extends Record<string, any>>(\n    obj: T,\n    excludeList: string[],\n  ): T {\n    if (obj === null || typeof obj !== \"object\") return obj;\n\n    const visited = new WeakSet();\n\n    const traverse = (o: any): void => {\n      if (visited.has(o)) return;\n      visited.add(o);\n\n      if (Array.isArray(o)) {\n        for (let i = 0; i < o.length; i++) {\n          const item = o[i];\n          if (item !== null && typeof item === \"object\") {\n            traverse(item);\n          }\n        }\n      } else {\n        for (const excludeKey of excludeList) {\n          if (excludeKey in o) {\n            delete o[excludeKey];\n          }\n        }\n        for (const key in o) {\n          const item = o[key];\n          if (item !== null && typeof item === \"object\") {\n            traverse(item);\n          }\n        }\n      }\n    };\n\n    traverse(obj);\n    return obj;\n  }\n}\n","import \"alepha/server/security\";\nimport { $module } from \"alepha\";\nimport { AlephaServer, type RequestConfigSchema } from \"alepha/server\";\nimport { AlephaServerCache } from \"alepha/server/cache\";\nimport { AlephaServerStatic } from \"alepha/server/static\";\nimport { $swagger } from \"./primitives/$swagger.ts\";\nimport { ServerSwaggerProvider } from \"./providers/ServerSwaggerProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$swagger.ts\";\nexport * from \"./providers/ServerSwaggerProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha/server\" {\n  interface ActionPrimitiveOptions<TConfig extends RequestConfigSchema> {\n    /**\n     * Short description of the route.\n     */\n    summary?: string;\n\n    /**\n     * Don't include this action in the Swagger documentation.\n     */\n    hide?: boolean;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha Server that provides Swagger documentation capabilities.\n * It generates OpenAPI v3 documentation for the server's endpoints ($action).\n * It also provides a Swagger UI for interactive API documentation.\n *\n * @see {@link ServerSwaggerProvider}\n * @module alepha.server.swagger\n */\nexport const AlephaServerSwagger = $module({\n  name: \"alepha.server.swagger\",\n  primitives: [$swagger],\n  services: [ServerSwaggerProvider],\n  register: (alepha) => {\n    alepha.with(AlephaServer);\n    alepha.with(AlephaServerCache);\n    alepha.with(AlephaServerStatic);\n    alepha.with(ServerSwaggerProvider);\n    alepha.store.push(\"alepha.build.assets\", \"alepha\");\n  },\n});\n"],"mappings":"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"}

package/dist/sms/index.d.ts

@@ -1,5 +1,5 @@
 import * as alepha0 from "alepha";
-import { Descriptor, InstantiableClass, KIND } from "alepha";
+import { InstantiableClass, KIND, Primitive } from "alepha";
 import * as alepha_logger0 from "alepha/logger";
 
 //#region src/sms/providers/SmsProvider.d.ts
@@ -21,17 +21,22 @@ type SmsSendOptions = {
   message: string;
 };
 //#endregion
-//#region src/sms/descriptors/$sms.d.ts
+//#region src/sms/errors/SmsError.d.ts
+declare class SmsError extends Error {
+  constructor(message: string, cause?: Error);
+}
+//#endregion
+//#region src/sms/primitives/$sms.d.ts
 declare const $sms: {
-  (options?: SmsDescriptorOptions): SmsDescriptor;
-  [KIND]: typeof SmsDescriptor;
+  (options?: SmsPrimitiveOptions): SmsPrimitive;
+  [KIND]: typeof SmsPrimitive;
 };
-interface SmsDescriptorOptions {
+interface SmsPrimitiveOptions {
   name?: string;
   provider?: InstantiableClass<SmsProvider> | "memory";
 }
 /**
- * SMS descriptor for sending SMS messages through various providers.
+ * SMS primitive for sending SMS messages through various providers.
  *
  * Usage:
  * ```typescript
@@ -47,7 +52,7 @@ interface SmsDescriptorOptions {
  * }
  * ```
  */
-declare class SmsDescriptor extends Descriptor<SmsDescriptorOptions> {
+declare class SmsPrimitive extends Primitive<SmsPrimitiveOptions> {
   protected readonly provider: SmsProvider;
   get name(): string;
   /**
@@ -57,11 +62,6 @@ declare class SmsDescriptor extends Descriptor<SmsDescriptorOptions> {
   protected $provider(): SmsProvider;
 }
 //#endregion
-//#region src/sms/errors/SmsError.d.ts
-declare class SmsError extends Error {
-  constructor(message: string, cause?: Error);
-}
-//#endregion
 //#region src/sms/providers/LocalSmsProvider.d.ts
 interface LocalSmsProviderOptions {
   /**
@@ -117,7 +117,7 @@ declare module "alepha" {
 /**
  * Provides SMS sending capabilities for Alepha applications with multiple provider backends.
  *
- * The SMS module enables declarative SMS sending through the `$sms` descriptor, allowing you to send
+ * The SMS module enables declarative SMS sending through the `$sms` primitive, allowing you to send
  * text messages through different providers: memory (for testing) or local file system.
  * It supports automatic provider selection based on environment configuration.
  *
@@ -126,5 +126,5 @@ declare module "alepha" {
  */
 declare const AlephaSms: alepha0.Service<alepha0.Module>;
 //#endregion
-export { $sms, AlephaSms, LocalSmsProvider, LocalSmsProviderOptions, MemorySmsProvider, SmsDescriptor, SmsDescriptorOptions, SmsError, SmsProvider, SmsRecord, SmsSendOptions };
+export { $sms, AlephaSms, LocalSmsProvider, LocalSmsProviderOptions, MemorySmsProvider, SmsError, SmsPrimitive, SmsPrimitiveOptions, SmsProvider, SmsRecord, SmsSendOptions };
 //# sourceMappingURL=index.d.ts.map

package/dist/sms/index.js

@@ -1,4 +1,4 @@
-import { $module, Descriptor, KIND, createDescriptor } from "alepha";
+import { $module, KIND, Primitive, createPrimitive } from "alepha";
 import { $logger } from "alepha/logger";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
@@ -37,10 +37,10 @@ var MemorySmsProvider = class {
 var SmsProvider = class {};
 
 //#endregion
-//#region src/sms/descriptors/$sms.ts
-const $sms = (options = {}) => createDescriptor(SmsDescriptor, options);
+//#region src/sms/primitives/$sms.ts
+const $sms = (options = {}) => createPrimitive(SmsPrimitive, options);
 /**
-* SMS descriptor for sending SMS messages through various providers.
+* SMS primitive for sending SMS messages through various providers.
 *
 * Usage:
 * ```typescript
@@ -56,7 +56,7 @@ const $sms = (options = {}) => createDescriptor(SmsDescriptor, options);
 * }
 * ```
 */
-var SmsDescriptor = class extends Descriptor {
+var SmsPrimitive = class extends Primitive {
 	provider = this.$provider();
 	get name() {
 		return this.options.name ?? `${this.config.propertyKey}`;
@@ -87,7 +87,7 @@ var SmsDescriptor = class extends Descriptor {
 		return this.alepha.inject(this.options.provider);
 	}
 };
-$sms[KIND] = SmsDescriptor;
+$sms[KIND] = SmsPrimitive;
 
 //#endregion
 //#region src/sms/errors/SmsError.ts
@@ -159,7 +159,7 @@ ${message}
 /**
 * Provides SMS sending capabilities for Alepha applications with multiple provider backends.
 *
-* The SMS module enables declarative SMS sending through the `$sms` descriptor, allowing you to send
+* The SMS module enables declarative SMS sending through the `$sms` primitive, allowing you to send
 * text messages through different providers: memory (for testing) or local file system.
 * It supports automatic provider selection based on environment configuration.
 *
@@ -168,7 +168,7 @@ ${message}
 */
 const AlephaSms = $module({
 	name: "alepha.sms",
-	descriptors: [$sms],
+	primitives: [$sms],
 	services: [
 		SmsProvider,
 		MemorySmsProvider,
@@ -182,5 +182,5 @@ const AlephaSms = $module({
 });
 
 //#endregion
-export { $sms, AlephaSms, LocalSmsProvider, MemorySmsProvider, SmsDescriptor, SmsError, SmsProvider };
+export { $sms, AlephaSms, LocalSmsProvider, MemorySmsProvider, SmsError, SmsPrimitive, SmsProvider };
 //# sourceMappingURL=index.js.map

package/dist/sms/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["message"],"sources":["../../src/sms/providers/MemorySmsProvider.ts","../../src/sms/providers/SmsProvider.ts","../../src/sms/descriptors/$sms.ts","../../src/sms/errors/SmsError.ts","../../src/sms/providers/LocalSmsProvider.ts","../../src/sms/index.ts"],"sourcesContent":["import { $logger } from \"alepha/logger\";\nimport type { SmsProvider, SmsSendOptions } from \"./SmsProvider.ts\";\n\nexport interface SmsRecord {\n  to: string;\n  message: string;\n  sentAt: Date;\n}\n\nexport class MemorySmsProvider implements SmsProvider {\n  protected readonly log = $logger();\n  public records: SmsRecord[] = [];\n\n  public async send(options: SmsSendOptions): Promise<void> {\n    const { to, message } = options;\n    this.log.debug(\"Sending SMS to memory store\", { to, message });\n\n    for (const recipient of Array.isArray(to) ? to : [to]) {\n      this.records.push({\n        to: recipient,\n        message,\n        sentAt: new Date(),\n      });\n    }\n  }\n\n  /**\n   * Get the last SMS sent (for testing purposes).\n   */\n  public get last(): SmsRecord | undefined {\n    return this.records[this.records.length - 1];\n  }\n}\n","/**\n * SMS provider interface.\n *\n * All methods are asynchronous and return promises.\n */\nexport abstract class SmsProvider {\n  /**\n   * Send an SMS.\n   *\n   * @return Promise that resolves when the SMS is sent.\n   */\n  public abstract send(options: SmsSendOptions): Promise<void>;\n}\n\nexport type SmsSendOptions = {\n  to: string | string[];\n  message: string;\n};\n","import {\n  createDescriptor,\n  Descriptor,\n  type InstantiableClass,\n  KIND,\n} from \"alepha\";\nimport { MemorySmsProvider } from \"../providers/MemorySmsProvider.ts\";\nimport type { SmsSendOptions } from \"../providers/SmsProvider.ts\";\nimport { SmsProvider } from \"../providers/SmsProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport const $sms = (options: SmsDescriptorOptions = {}) =>\n  createDescriptor(SmsDescriptor, options);\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface SmsDescriptorOptions {\n  name?: string;\n  provider?: InstantiableClass<SmsProvider> | \"memory\";\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * SMS descriptor for sending SMS messages through various providers.\n *\n * Usage:\n * ```typescript\n * class MyService {\n *   private readonly welcomeSms = $sms({ name: \"welcome\" });\n *\n *   async sendWelcome(phoneNumber: string, userName: string) {\n *     await this.welcomeSms.send({\n *       to: phoneNumber,\n *       message: `Hello ${userName}! Welcome to our service.`\n *     });\n *   }\n * }\n * ```\n */\nexport class SmsDescriptor extends Descriptor<SmsDescriptorOptions> {\n  protected readonly provider = this.$provider();\n\n  public get name() {\n    return this.options.name ?? `${this.config.propertyKey}`;\n  }\n\n  /**\n   * Send an SMS using the configured provider.\n   */\n  public async send(options: SmsSendOptions): Promise<void> {\n    await this.alepha.events.emit(\"sms:sending\", {\n      to: options.to,\n      template: this.name,\n      variables: {},\n      provider: this.provider,\n      abort: () => {\n        throw new Error(\"SMS sending aborted by hook\");\n      },\n    });\n\n    await this.provider.send(options);\n\n    await this.alepha.events.emit(\"sms:sent\", {\n      to: options.to,\n      template: this.name,\n      provider: this.provider,\n    });\n  }\n\n  protected $provider(): SmsProvider {\n    if (!this.options.provider) {\n      return this.alepha.inject(SmsProvider);\n    }\n    if (this.options.provider === \"memory\") {\n      return this.alepha.inject(MemorySmsProvider);\n    }\n    return this.alepha.inject(this.options.provider);\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n$sms[KIND] = SmsDescriptor;\n","export class SmsError extends Error {\n  constructor(message: string, cause?: Error) {\n    super(message);\n    this.name = \"SmsError\";\n    this.cause = cause;\n  }\n}\n","import * as fs from \"node:fs/promises\";\nimport * as path from \"node:path\";\nimport { $logger } from \"alepha/logger\";\nimport { SmsError } from \"../errors/SmsError.ts\";\nimport type { SmsProvider, SmsSendOptions } from \"./SmsProvider.ts\";\n\nexport interface LocalSmsProviderOptions {\n  /**\n   * Directory to save SMS files.\n   * @default \"node_modules/.sms\" (relative to project root)\n   */\n  directory?: string;\n}\n\nexport class LocalSmsProvider implements SmsProvider {\n  protected readonly log = $logger();\n  protected readonly directory: string;\n\n  constructor(options: LocalSmsProviderOptions = {}) {\n    this.directory = options.directory ?? \"node_modules/.sms\";\n  }\n\n  public async send(options: SmsSendOptions): Promise<void> {\n    const { to, message } = options;\n\n    this.log.debug(\"Sending SMS to local file\", {\n      to,\n      message,\n      directory: this.directory,\n    });\n\n    try {\n      // Ensure directory exists\n      await fs.mkdir(this.directory, { recursive: true });\n\n      // Create filename: phone+date\n      const timestamp = new Date().toISOString().replace(/[:.]/g, \"-\");\n      for (const recipient of Array.isArray(to) ? to : [to]) {\n        const sanitizedPhone = recipient.replace(/[^0-9+]/g, \"_\");\n        const filename = `${sanitizedPhone}+${timestamp}.txt`;\n        const filepath = path.join(this.directory, filename);\n\n        // Create text content\n        const textContent = this.createSmsText({\n          to: recipient,\n          message,\n        });\n\n        // Write to file\n        await fs.writeFile(filepath, textContent, \"utf8\");\n\n        this.log.info(\"SMS saved to local file\", { filepath, to });\n      }\n    } catch (error) {\n      const message = `Failed to save SMS to local file: ${error instanceof Error ? error.message : String(error)}`;\n      this.log.error(message, { to, directory: this.directory });\n      throw new SmsError(message, error instanceof Error ? error : undefined);\n    }\n  }\n\n  public createSmsText(options: { to: string; message: string }): string {\n    const { to, message } = options;\n    const timestamp = new Date().toISOString();\n\n    return `SMS Message\n===========\n\nSent: ${timestamp}\nTo: ${to}\n\nMessage:\n--------\n${message}\n`;\n  }\n}\n","import { $module } from \"alepha\";\nimport { $sms } from \"./descriptors/$sms.ts\";\nimport { LocalSmsProvider } from \"./providers/LocalSmsProvider.ts\";\nimport { MemorySmsProvider } from \"./providers/MemorySmsProvider.ts\";\nimport { SmsProvider } from \"./providers/SmsProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./descriptors/$sms.ts\";\nexport * from \"./errors/SmsError.ts\";\nexport * from \"./providers/LocalSmsProvider.ts\";\nexport * from \"./providers/MemorySmsProvider.ts\";\nexport * from \"./providers/SmsProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha\" {\n  interface Hooks {\n    \"sms:sending\": {\n      to: string | string[];\n      template: string;\n      variables: Record<string, unknown>;\n      provider: SmsProvider;\n      abort(): void;\n    };\n    \"sms:sent\": {\n      to: string | string[];\n      template: string;\n      provider: SmsProvider;\n    };\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Provides SMS sending capabilities for Alepha applications with multiple provider backends.\n *\n * The SMS module enables declarative SMS sending through the `$sms` descriptor, allowing you to send\n * text messages through different providers: memory (for testing) or local file system.\n * It supports automatic provider selection based on environment configuration.\n *\n * @see {@link SmsProvider}\n * @module alepha.sms\n */\nexport const AlephaSms = $module({\n  name: \"alepha.sms\",\n  descriptors: [$sms],\n  services: [SmsProvider, MemorySmsProvider, LocalSmsProvider],\n  register: (alepha) =>\n    alepha.with({\n      optional: true,\n      provide: SmsProvider,\n      use: MemorySmsProvider,\n    }),\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["message"],"sources":["../../src/sms/providers/MemorySmsProvider.ts","../../src/sms/providers/SmsProvider.ts","../../src/sms/primitives/$sms.ts","../../src/sms/errors/SmsError.ts","../../src/sms/providers/LocalSmsProvider.ts","../../src/sms/index.ts"],"sourcesContent":["import { $logger } from \"alepha/logger\";\nimport type { SmsProvider, SmsSendOptions } from \"./SmsProvider.ts\";\n\nexport interface SmsRecord {\n  to: string;\n  message: string;\n  sentAt: Date;\n}\n\nexport class MemorySmsProvider implements SmsProvider {\n  protected readonly log = $logger();\n  public records: SmsRecord[] = [];\n\n  public async send(options: SmsSendOptions): Promise<void> {\n    const { to, message } = options;\n    this.log.debug(\"Sending SMS to memory store\", { to, message });\n\n    for (const recipient of Array.isArray(to) ? to : [to]) {\n      this.records.push({\n        to: recipient,\n        message,\n        sentAt: new Date(),\n      });\n    }\n  }\n\n  /**\n   * Get the last SMS sent (for testing purposes).\n   */\n  public get last(): SmsRecord | undefined {\n    return this.records[this.records.length - 1];\n  }\n}\n","/**\n * SMS provider interface.\n *\n * All methods are asynchronous and return promises.\n */\nexport abstract class SmsProvider {\n  /**\n   * Send an SMS.\n   *\n   * @return Promise that resolves when the SMS is sent.\n   */\n  public abstract send(options: SmsSendOptions): Promise<void>;\n}\n\nexport type SmsSendOptions = {\n  to: string | string[];\n  message: string;\n};\n","import {\n  createPrimitive,\n  type InstantiableClass,\n  KIND,\n  Primitive,\n} from \"alepha\";\nimport { MemorySmsProvider } from \"../providers/MemorySmsProvider.ts\";\nimport type { SmsSendOptions } from \"../providers/SmsProvider.ts\";\nimport { SmsProvider } from \"../providers/SmsProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport const $sms = (options: SmsPrimitiveOptions = {}) =>\n  createPrimitive(SmsPrimitive, options);\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface SmsPrimitiveOptions {\n  name?: string;\n  provider?: InstantiableClass<SmsProvider> | \"memory\";\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * SMS primitive for sending SMS messages through various providers.\n *\n * Usage:\n * ```typescript\n * class MyService {\n *   private readonly welcomeSms = $sms({ name: \"welcome\" });\n *\n *   async sendWelcome(phoneNumber: string, userName: string) {\n *     await this.welcomeSms.send({\n *       to: phoneNumber,\n *       message: `Hello ${userName}! Welcome to our service.`\n *     });\n *   }\n * }\n * ```\n */\nexport class SmsPrimitive extends Primitive<SmsPrimitiveOptions> {\n  protected readonly provider = this.$provider();\n\n  public get name() {\n    return this.options.name ?? `${this.config.propertyKey}`;\n  }\n\n  /**\n   * Send an SMS using the configured provider.\n   */\n  public async send(options: SmsSendOptions): Promise<void> {\n    await this.alepha.events.emit(\"sms:sending\", {\n      to: options.to,\n      template: this.name,\n      variables: {},\n      provider: this.provider,\n      abort: () => {\n        throw new Error(\"SMS sending aborted by hook\");\n      },\n    });\n\n    await this.provider.send(options);\n\n    await this.alepha.events.emit(\"sms:sent\", {\n      to: options.to,\n      template: this.name,\n      provider: this.provider,\n    });\n  }\n\n  protected $provider(): SmsProvider {\n    if (!this.options.provider) {\n      return this.alepha.inject(SmsProvider);\n    }\n    if (this.options.provider === \"memory\") {\n      return this.alepha.inject(MemorySmsProvider);\n    }\n    return this.alepha.inject(this.options.provider);\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n$sms[KIND] = SmsPrimitive;\n","export class SmsError extends Error {\n  constructor(message: string, cause?: Error) {\n    super(message);\n    this.name = \"SmsError\";\n    this.cause = cause;\n  }\n}\n","import * as fs from \"node:fs/promises\";\nimport * as path from \"node:path\";\nimport { $logger } from \"alepha/logger\";\nimport { SmsError } from \"../errors/SmsError.ts\";\nimport type { SmsProvider, SmsSendOptions } from \"./SmsProvider.ts\";\n\nexport interface LocalSmsProviderOptions {\n  /**\n   * Directory to save SMS files.\n   * @default \"node_modules/.sms\" (relative to project root)\n   */\n  directory?: string;\n}\n\nexport class LocalSmsProvider implements SmsProvider {\n  protected readonly log = $logger();\n  protected readonly directory: string;\n\n  constructor(options: LocalSmsProviderOptions = {}) {\n    this.directory = options.directory ?? \"node_modules/.sms\";\n  }\n\n  public async send(options: SmsSendOptions): Promise<void> {\n    const { to, message } = options;\n\n    this.log.debug(\"Sending SMS to local file\", {\n      to,\n      message,\n      directory: this.directory,\n    });\n\n    try {\n      // Ensure directory exists\n      await fs.mkdir(this.directory, { recursive: true });\n\n      // Create filename: phone+date\n      const timestamp = new Date().toISOString().replace(/[:.]/g, \"-\");\n      for (const recipient of Array.isArray(to) ? to : [to]) {\n        const sanitizedPhone = recipient.replace(/[^0-9+]/g, \"_\");\n        const filename = `${sanitizedPhone}+${timestamp}.txt`;\n        const filepath = path.join(this.directory, filename);\n\n        // Create text content\n        const textContent = this.createSmsText({\n          to: recipient,\n          message,\n        });\n\n        // Write to file\n        await fs.writeFile(filepath, textContent, \"utf8\");\n\n        this.log.info(\"SMS saved to local file\", { filepath, to });\n      }\n    } catch (error) {\n      const message = `Failed to save SMS to local file: ${error instanceof Error ? error.message : String(error)}`;\n      this.log.error(message, { to, directory: this.directory });\n      throw new SmsError(message, error instanceof Error ? error : undefined);\n    }\n  }\n\n  public createSmsText(options: { to: string; message: string }): string {\n    const { to, message } = options;\n    const timestamp = new Date().toISOString();\n\n    return `SMS Message\n===========\n\nSent: ${timestamp}\nTo: ${to}\n\nMessage:\n--------\n${message}\n`;\n  }\n}\n","import { $module } from \"alepha\";\nimport { $sms } from \"./primitives/$sms.ts\";\nimport { LocalSmsProvider } from \"./providers/LocalSmsProvider.ts\";\nimport { MemorySmsProvider } from \"./providers/MemorySmsProvider.ts\";\nimport { SmsProvider } from \"./providers/SmsProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./errors/SmsError.ts\";\nexport * from \"./primitives/$sms.ts\";\nexport * from \"./providers/LocalSmsProvider.ts\";\nexport * from \"./providers/MemorySmsProvider.ts\";\nexport * from \"./providers/SmsProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha\" {\n  interface Hooks {\n    \"sms:sending\": {\n      to: string | string[];\n      template: string;\n      variables: Record<string, unknown>;\n      provider: SmsProvider;\n      abort(): void;\n    };\n    \"sms:sent\": {\n      to: string | string[];\n      template: string;\n      provider: SmsProvider;\n    };\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Provides SMS sending capabilities for Alepha applications with multiple provider backends.\n *\n * The SMS module enables declarative SMS sending through the `$sms` primitive, allowing you to send\n * text messages through different providers: memory (for testing) or local file system.\n * It supports automatic provider selection based on environment configuration.\n *\n * @see {@link SmsProvider}\n * @module alepha.sms\n */\nexport const AlephaSms = $module({\n  name: \"alepha.sms\",\n  primitives: [$sms],\n  services: [SmsProvider, MemorySmsProvider, LocalSmsProvider],\n  register: (alepha) =>\n    alepha.with({\n      optional: true,\n      provide: SmsProvider,\n      use: MemorySmsProvider,\n    }),\n});\n"],"mappings":"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"}

package/dist/thread/index.d.ts

@@ -1,13 +1,13 @@
 import * as alepha1 from "alepha";
-import { Descriptor, KIND, TSchema } from "alepha";
+import { KIND, Primitive, TSchema } from "alepha";
 import * as alepha_logger0 from "alepha/logger";
 
-//#region src/thread/descriptors/$thread.d.ts
+//#region src/thread/primitives/$thread.d.ts
 
 /**
- * Creates a worker thread descriptor for offloading CPU-intensive tasks to separate threads.
+ * Creates a worker thread primitive for offloading CPU-intensive tasks to separate threads.
  *
- * This descriptor enables you to run JavaScript code in Node.js worker threads, allowing you to
+ * This primitive enables you to run JavaScript code in Node.js worker threads, allowing you to
  * leverage multiple CPU cores and avoid blocking the main event loop. It provides a pool-based
  * approach with intelligent thread reuse and automatic lifecycle management.
  *
@@ -119,10 +119,10 @@ import * as alepha_logger0 from "alepha/logger";
  * ```
  */
 declare const $thread: {
-  (options: ThreadDescriptorOptions): ThreadDescriptor;
-  [KIND]: typeof ThreadDescriptor;
+  (options: ThreadPrimitiveOptions): ThreadPrimitive;
+  [KIND]: typeof ThreadPrimitive;
 };
-interface ThreadDescriptorOptions {
+interface ThreadPrimitiveOptions {
   /**
    * Unique name for this thread worker.
    *
@@ -131,7 +131,7 @@ interface ThreadDescriptorOptions {
    * - Logging and debugging
    * - Error messages and stack traces
    *
-   * If not provided, defaults to the property key of the descriptor.
+   * If not provided, defaults to the property key of the primitive.
    *
    * @example "image-processor"
    * @example "crypto-worker"
@@ -203,7 +203,7 @@ interface ThreadDescriptorOptions {
    */
   idleTimeout?: number;
 }
-declare class ThreadDescriptor extends Descriptor<ThreadDescriptorOptions> {
+declare class ThreadPrimitive extends Primitive<ThreadPrimitiveOptions> {
   protected readonly script: string;
   static readonly globalPool: Map<string, ThreadPool>;
   get name(): string;
@@ -238,7 +238,7 @@ declare class ThreadProvider {
   protected readonly env: {
     ALEPHA_WORKER?: string | undefined;
   };
-  protected readonly ready: alepha1.HookDescriptor<"ready">;
+  protected readonly ready: alepha1.HookPrimitive<"ready">;
   static cleanup(): Promise<void>;
 }
 //#endregion
@@ -256,5 +256,5 @@ declare module "alepha" {
  */
 declare const AlephaThread: alepha1.Service<alepha1.Module>;
 //#endregion
-export { $thread, AlephaThread, ThreadDescriptor, ThreadDescriptorOptions, ThreadProvider };
+export { $thread, AlephaThread, ThreadPrimitive, ThreadPrimitiveOptions, ThreadProvider };
 //# sourceMappingURL=index.d.ts.map

package/dist/thread/index.js

@@ -1,13 +1,13 @@
-import { $env, $hook, $module, Alepha, Descriptor, KIND, TypeBoxValue, createDescriptor, t } from "alepha";
+import { $env, $hook, $module, Alepha, KIND, Primitive, TypeBoxValue, createPrimitive, t } from "alepha";
 import { cpus } from "node:os";
 import { MessageChannel, Worker, parentPort, workerData } from "node:worker_threads";
 import { $logger } from "alepha/logger";
 
-//#region src/thread/descriptors/$thread.ts
+//#region src/thread/primitives/$thread.ts
 /**
-* Creates a worker thread descriptor for offloading CPU-intensive tasks to separate threads.
+* Creates a worker thread primitive for offloading CPU-intensive tasks to separate threads.
 *
-* This descriptor enables you to run JavaScript code in Node.js worker threads, allowing you to
+* This primitive enables you to run JavaScript code in Node.js worker threads, allowing you to
 * leverage multiple CPU cores and avoid blocking the main event loop. It provides a pool-based
 * approach with intelligent thread reuse and automatic lifecycle management.
 *
@@ -119,9 +119,9 @@ import { $logger } from "alepha/logger";
 * ```
 */
 const $thread = (options) => {
-	return createDescriptor(ThreadDescriptor, options);
+	return createPrimitive(ThreadPrimitive, options);
 };
-var ThreadDescriptor = class ThreadDescriptor extends Descriptor {
+var ThreadPrimitive = class ThreadPrimitive extends Primitive {
 	script = process.argv[1];
 	static globalPool = /* @__PURE__ */ new Map();
 	get name() {
@@ -134,8 +134,8 @@ var ThreadDescriptor = class ThreadDescriptor extends Descriptor {
 		return this.options.idleTimeout || 6e4;
 	}
 	getPool() {
-		if (!ThreadDescriptor.globalPool.has(this.name)) ThreadDescriptor.globalPool.set(this.name, new ThreadPool(this.name, this.maxPoolSize, this.idleTimeout, this.script));
-		return ThreadDescriptor.globalPool.get(this.name);
+		if (!ThreadPrimitive.globalPool.has(this.name)) ThreadPrimitive.globalPool.set(this.name, new ThreadPool(this.name, this.maxPoolSize, this.idleTimeout, this.script));
+		return ThreadPrimitive.globalPool.get(this.name);
 	}
 	async execute(data, schema) {
 		if (schema && data) try {
@@ -150,10 +150,10 @@ var ThreadDescriptor = class ThreadDescriptor extends Descriptor {
 	}
 	async terminate() {
 		await this.getPool().terminate();
-		ThreadDescriptor.globalPool.delete(this.name);
+		ThreadPrimitive.globalPool.delete(this.name);
 	}
 };
-$thread[KIND] = ThreadDescriptor;
+$thread[KIND] = ThreadPrimitive;
 var ThreadPool = class {
 	instances = [];
 	queue = [];
@@ -288,12 +288,12 @@ var ThreadProvider = class {
 		handler: async (alepha) => {
 			const worker = this.env.ALEPHA_WORKER;
 			if (!worker) return;
-			const threadDescriptor = alepha.descriptors($thread).find((thread) => thread.name === worker);
-			if (!threadDescriptor) {
+			const threadPrimitive = alepha.primitives($thread).find((thread) => thread.name === worker);
+			if (!threadPrimitive) {
 				this.log.error(`Thread not found: ${worker}`);
 				return;
 			}
-			this.log.info(`Thread ready: ${threadDescriptor.name}`);
+			this.log.info(`Thread ready: ${threadPrimitive.name}`);
 			const communicationPort = workerData?.port || parentPort;
 			if (!communicationPort) {
 				this.log.error("No communication port available");
@@ -301,8 +301,8 @@ var ThreadProvider = class {
 			}
 			communicationPort.on("message", async (message) => {
 				if (message.type === "execute") try {
-					this.log.debug(`Executing thread handler: ${threadDescriptor.name}`);
-					const result = await threadDescriptor.options.handler();
+					this.log.debug(`Executing thread handler: ${threadPrimitive.name}`);
+					const result = await threadPrimitive.options.handler();
 					communicationPort.postMessage({
 						id: message.id,
 						type: "response",
@@ -338,10 +338,10 @@ Alepha.prototype.isWorkerThread = function() {
 */
 const AlephaThread = $module({
 	name: "alepha.thread",
-	descriptors: [$thread],
+	primitives: [$thread],
 	services: [ThreadProvider]
 });
 
 //#endregion
-export { $thread, AlephaThread, ThreadDescriptor, ThreadProvider };
+export { $thread, AlephaThread, ThreadPrimitive, ThreadProvider };
 //# sourceMappingURL=index.js.map