alepha 0.13.0 → 0.13.2

package/dist/server-links/index.d.cts

@@ -1,513 +0,0 @@
-import * as alepha21 from "alepha";
-import { Alepha, Async, Descriptor, KIND, Static } from "alepha";
-import { ServiceAccountDescriptor, UserAccount, UserAccountToken } from "alepha/security";
-import * as alepha_server0 from "alepha/server";
-import { ActionDescriptor, ClientRequestEntry, ClientRequestOptions, ClientRequestResponse, FetchOptions, FetchResponse, HttpClient, RequestConfigSchema, ServerHandler, ServerRequest, ServerRequestConfigEntry, ServerResponseBody, ServerRouterProvider, ServerTimingProvider } from "alepha/server";
-import * as alepha_logger0 from "alepha/logger";
-import * as alepha_retry0 from "alepha/retry";
-
-//#region src/server-security/providers/ServerBasicAuthProvider.d.ts
-interface BasicAuthOptions {
-  username: string;
-  password: string;
-}
-//#endregion
-//#region src/server-security/providers/ServerSecurityProvider.d.ts
-
-type ServerRouteSecure = {
-  realm?: string;
-  basic?: BasicAuthOptions;
-};
-//#endregion
-//#region src/server-security/index.d.ts
-declare module "alepha" {
-  interface State {
-    /**
-     * Real (or fake) user account, used for internal actions.
-     *
-     * If you define this, you assume that all actions are executed by this user by default.
-     * > To force a different user, you need to pass it explicitly in the options.
-     */
-    "alepha.server.security.system.user"?: UserAccountToken;
-    /**
-     * The authenticated user account attached to the server request state.
-     *
-     * @internal
-     */
-    "alepha.server.request.user"?: UserAccount;
-  }
-}
-declare module "alepha/server" {
-  interface ServerRequest<TConfig> {
-    user?: UserAccountToken;
-  }
-  interface ServerActionRequest<TConfig> {
-    user: UserAccountToken;
-  }
-  interface ServerRoute {
-    /**
-     * If true, the route will be protected by the security provider.
-     * All actions are secure by default, but you can disable it for specific actions.
-     */
-    secure?: boolean | ServerRouteSecure;
-  }
-  interface ClientRequestOptions extends FetchOptions {
-    /**
-     * Forward user from the previous request.
-     * If "system", use system user. @see {ServerSecurityProvider.localSystemUser}
-     * If "context", use the user from the current context (e.g. request).
-     *
-     * @default "system" if provided, else "context" if available.
-     */
-    user?: UserAccountToken | "system" | "context";
-  }
-}
-/**
- * Plugin for Alepha Server that provides security features. Based on the Alepha Security module.
- *
- * By default, all $action will be guarded by a permission check.
- *
- * @see {@link ServerSecurityProvider}
- * @module alepha.server.security
- */
-//#endregion
-//#region src/server-links/schemas/apiLinksResponseSchema.d.ts
-declare const apiLinkSchema: alepha21.TObject<{
-  name: alepha21.TString;
-  group: alepha21.TOptional<alepha21.TString>;
-  path: alepha21.TString;
-  method: alepha21.TOptional<alepha21.TString>;
-  requestBodyType: alepha21.TOptional<alepha21.TString>;
-  service: alepha21.TOptional<alepha21.TString>;
-}>;
-declare const apiLinksResponseSchema: alepha21.TObject<{
-  prefix: alepha21.TOptional<alepha21.TString>;
-  links: alepha21.TArray<alepha21.TObject<{
-    name: alepha21.TString;
-    group: alepha21.TOptional<alepha21.TString>;
-    path: alepha21.TString;
-    method: alepha21.TOptional<alepha21.TString>;
-    requestBodyType: alepha21.TOptional<alepha21.TString>;
-    service: alepha21.TOptional<alepha21.TString>;
-  }>>;
-}>;
-type ApiLinksResponse = Static<typeof apiLinksResponseSchema>;
-type ApiLink = Static<typeof apiLinkSchema>;
-//#endregion
-//#region src/server-links/providers/LinkProvider.d.ts
-/**
- * Browser, SSR friendly, service to handle links.
- */
-declare class LinkProvider {
-  static path: {
-    apiLinks: string;
-    apiSchema: string;
-  };
-  protected readonly log: alepha_logger0.Logger;
-  protected readonly alepha: Alepha;
-  protected readonly httpClient: HttpClient;
-  protected serverLinks: Array<HttpClientLink>;
-  /**
-   * Get applicative links registered on the server.
-   * This does not include lazy-loaded remote links.
-   */
-  getServerLinks(): HttpClientLink[];
-  /**
-   * Register a new link for the application.
-   */
-  registerLink(link: HttpClientLink): void;
-  get links(): HttpClientLink[];
-  /**
-   * Force browser to refresh links from the server.
-   */
-  fetchLinks(): Promise<HttpClientLink[]>;
-  /**
-   * Create a virtual client that can be used to call actions.
-   *
-   * Use js Proxy under the hood.
-   */
-  client<T extends object>(scope?: ClientScope): HttpVirtualClient<T>;
-  /**
-   * Check if a link with the given name exists.
-   * @param name
-   */
-  can(name: string): boolean;
-  /**
-   * Resolve a link by its name and call it.
-   * - If link is local, it will call the local handler.
-   * - If link is remote, it will make a fetch request to the remote server.
-   */
-  follow(name: string, config?: Partial<ServerRequestConfigEntry>, options?: ClientRequestOptions & ClientScope): Promise<any>;
-  protected createVirtualAction<T extends RequestConfigSchema>(name: string, scope?: ClientScope): VirtualAction<T>;
-  protected followRemote(link: HttpClientLink, config?: Partial<ServerRequestConfigEntry>, options?: ClientRequestOptions): Promise<FetchResponse>;
-  protected getLinkByName(name: string, options?: ClientScope): Promise<HttpClientLink>;
-}
-interface HttpClientLink extends ApiLink {
-  secured?: boolean | ServerRouteSecure;
-  prefix?: string;
-  host?: string;
-  service?: string;
-  schema?: RequestConfigSchema;
-  handler?: (request: ServerRequest, options: ClientRequestOptions) => Async<ServerResponseBody>;
-}
-interface ClientScope {
-  group?: string;
-  service?: string;
-  hostname?: string;
-}
-type HttpVirtualClient<T> = { [K in keyof T as T[K] extends ActionDescriptor<RequestConfigSchema> ? K : never]: T[K] extends ActionDescriptor<infer Schema> ? VirtualAction<Schema> : never };
-interface VirtualAction<T extends RequestConfigSchema> extends Pick<ActionDescriptor<T>, "name" | "run" | "fetch"> {
-  (config?: ClientRequestEntry<T>, opts?: ClientRequestOptions): Promise<ClientRequestResponse<T>>;
-  can: () => boolean;
-}
-//#endregion
-//#region src/server-links/descriptors/$client.d.ts
-/**
- * Create a new client.
- */
-declare const $client: {
-  <T extends object>(scope?: ClientScope): HttpVirtualClient<T>;
-  [KIND]: string;
-};
-//#endregion
-//#region src/server-proxy/descriptors/$proxy.d.ts
-type ProxyDescriptorOptions = {
-  /**
-   * Path pattern to match for proxying requests.
-   *
-   * Supports wildcards and path parameters:
-   * - `/api/*` - Matches all paths starting with `/api/`
-   * - `/api/v1/*` - Matches all paths starting with `/api/v1/`
-   * - `/users/:id` - Matches `/users/123`, `/users/abc`, etc.
-   *
-   * @example "/api/*"
-   * @example "/secure/admin/*"
-   * @example "/users/:id/posts"
-   */
-  path: string;
-  /**
-   * Target URL to which matching requests should be forwarded.
-   *
-   * Can be either:
-   * - **Static string**: A fixed URL like `"https://api.example.com"`
-   * - **Dynamic function**: A function that returns the URL, enabling runtime target resolution
-   *
-   * The target URL will be combined with the remaining path from the original request.
-   *
-   * @example "https://api.example.com"
-   * @example () => process.env.API_URL || "http://localhost:3001"
-   */
-  target: string | (() => string);
-  /**
-   * Whether this proxy is disabled.
-   *
-   * When `true`, requests matching the path will not be proxied and will be handled
-   * by other routes or return 404. Useful for feature toggles or conditional proxying.
-   *
-   * @default false
-   * @example !process.env.ENABLE_PROXY
-   */
-  disabled?: boolean;
-  /**
-   * Hook called before forwarding the request to the target server.
-   *
-   * Use this to:
-   * - Add authentication headers
-   * - Modify request headers or body
-   * - Add request tracking/logging
-   * - Transform the request before forwarding
-   *
-   * @param request - The original incoming server request
-   * @param proxyRequest - The request that will be sent to the target (modifiable)
-   *
-   * @example
-   * ```ts
-   * beforeRequest: async (request, proxyRequest) => {
-   *   proxyRequest.headers = {
-   *     ...proxyRequest.headers,
-   *     'Authorization': `Bearer ${await getToken()}`,
-   *     'X-Request-ID': generateRequestId()
-   *   };
-   * }
-   * ```
-   */
-  beforeRequest?: (request: ServerRequest, proxyRequest: RequestInit) => Async<void>;
-  /**
-   * Hook called after receiving the response from the target server.
-   *
-   * Use this to:
-   * - Log response details for monitoring
-   * - Add custom headers to the response
-   * - Transform response data
-   * - Handle error responses
-   *
-   * @param request - The original incoming server request
-   * @param proxyResponse - The response received from the target server
-   *
-   * @example
-   * ```ts
-   * afterResponse: async (request, proxyResponse) => {
-   *   console.log(`Proxy ${request.method} ${request.url} -> ${proxyResponse.status}`);
-   *
-   *   if (!proxyResponse.ok) {
-   *     await logError(`Proxy error: ${proxyResponse.status}`, { request, response: proxyResponse });
-   *   }
-   * }
-   * ```
-   */
-  afterResponse?: (request: ServerRequest, proxyResponse: Response) => Async<void>;
-  /**
-   * Function to rewrite the URL before sending to the target server.
-   *
-   * Use this to:
-   * - Remove or add path prefixes
-   * - Transform path parameters
-   * - Modify query parameters
-   * - Change the URL structure entirely
-   *
-   * The function receives a mutable URL object and should modify it in-place.
-   *
-   * @param url - The URL object to modify (mutable)
-   *
-   * @example
-   * ```ts
-   * // Remove /api prefix when forwarding
-   * rewrite: (url) => {
-   *   url.pathname = url.pathname.replace('/api', '');
-   * }
-   * ```
-   *
-   * @example
-   * ```ts
-   * // Add version prefix
-   * rewrite: (url) => {
-   *   url.pathname = `/v2${url.pathname}`;
-   * }
-   * ```
-   */
-  rewrite?: (url: URL) => void;
-};
-//#endregion
-//#region src/server-proxy/providers/ServerProxyProvider.d.ts
-declare class ServerProxyProvider {
-  protected readonly log: alepha_logger0.Logger;
-  protected readonly routerProvider: ServerRouterProvider;
-  protected readonly alepha: Alepha;
-  protected readonly configure: alepha21.HookDescriptor<"configure">;
-  createProxy(options: ProxyDescriptorOptions): void;
-  createProxyHandler(target: string, options: Omit<ProxyDescriptorOptions, "path">): ServerHandler;
-  private getRawRequestBody;
-}
-//#endregion
-//#region src/server-links/descriptors/$remote.d.ts
-/**
- * $remote is a descriptor that allows you to define remote service access.
- *
- * Use it only when you have 2 or more services that need to communicate with each other.
- *
- * All remote services can be exposed as actions, ... or not.
- *
- * You can add a service account if you want to use a security layer.
- */
-declare const $remote: {
-  (options: RemoteDescriptorOptions): RemoteDescriptor;
-  [KIND]: typeof RemoteDescriptor;
-};
-interface RemoteDescriptorOptions {
-  /**
-   * The URL of the remote service.
-   * You can use a function to generate the URL dynamically.
-   * You probably should use $env(env) to get the URL from the environment.
-   *
-   * @example
-   * ```ts
-   * import { $remote } from "alepha/server";
-   * import { $inject, t } from "alepha";
-   *
-   * class App {
-   *   env = $env(t.object({
-   *     REMOTE_URL: t.text({default: "http://localhost:3000"}),
-   *   }));
-   *   remote = $remote({
-   *     url: this.env.REMOTE_URL,
-   *   });
-   * }
-   * ```
-   */
-  url: string | (() => string);
-  /**
-   * The name of the remote service.
-   *
-   * @default Member of the class containing the remote service.
-   */
-  name?: string;
-  /**
-   * If true, all methods of the remote service will be exposed as actions in this context.
-   * > Note: Proxy will never use the service account, it just... proxies the request.
-   */
-  proxy?: boolean | Partial<ProxyDescriptorOptions & {
-    /**
-     * If true, the remote service won't be available internally, only through the proxy.
-     */
-    noInternal: boolean;
-  }>;
-  /**
-   * For communication between the server and the remote service with a security layer.
-   * This will be used for internal communication and will not be exposed to the client.
-   */
-  serviceAccount?: ServiceAccountDescriptor;
-}
-declare class RemoteDescriptor extends Descriptor<RemoteDescriptorOptions> {
-  get name(): string;
-}
-//#endregion
-//#region src/server-links/providers/RemoteDescriptorProvider.d.ts
-declare class RemoteDescriptorProvider {
-  protected readonly env: {
-    SERVER_API_PREFIX: string;
-  };
-  protected readonly alepha: Alepha;
-  protected readonly proxyProvider: ServerProxyProvider;
-  protected readonly linkProvider: LinkProvider;
-  protected readonly remotes: Array<ServerRemote>;
-  protected readonly log: alepha_logger0.Logger;
-  getRemotes(): ServerRemote[];
-  readonly configure: alepha21.HookDescriptor<"configure">;
-  readonly start: alepha21.HookDescriptor<"start">;
-  registerRemote(value: RemoteDescriptor): Promise<void>;
-  protected readonly fetchLinks: alepha_retry0.RetryDescriptorFn<(opts: FetchLinksOptions) => Promise<ApiLinksResponse>>;
-}
-interface FetchLinksOptions {
-  /**
-   * Name of the remote service.
-   */
-  service: string;
-  /**
-   * URL to fetch links from.
-   */
-  url: string;
-  /**
-   * Authorization header containing access token.
-   */
-  authorization?: string;
-}
-interface ServerRemote {
-  /**
-   * URL of the remote service.
-   */
-  url: string;
-  /**
-   * Name of the remote service.
-   */
-  name: string;
-  /**
-   * Expose links as endpoint. It's not only internal.
-   */
-  proxy: boolean;
-  /**
-   * It's only used inside the application.
-   */
-  internal: boolean;
-  /**
-   * Links fetcher.
-   */
-  links: (args: {
-    authorization?: string;
-  }) => Promise<ApiLinksResponse>;
-  /**
-   * Fetches schema for the remote service.
-   */
-  schema: (args: {
-    name: string;
-    authorization?: string;
-  }) => Promise<any>;
-  /**
-   * Force a default access token provider when not provided.
-   */
-  serviceAccount?: ServiceAccountDescriptor;
-  /**
-   * Prefix for the remote service links.
-   */
-  prefix: string;
-}
-//#endregion
-//#region src/server-links/providers/ServerLinksProvider.d.ts
-declare class ServerLinksProvider {
-  protected readonly env: {
-    SERVER_API_PREFIX: string;
-  };
-  protected readonly alepha: Alepha;
-  protected readonly linkProvider: LinkProvider;
-  protected readonly remoteProvider: RemoteDescriptorProvider;
-  protected readonly serverTimingProvider: ServerTimingProvider;
-  get prefix(): string;
-  readonly onRoute: alepha21.HookDescriptor<"configure">;
-  /**
-   * First API - Get all API links for the user.
-   *
-   * This is based on the user's permissions.
-   */
-  readonly links: alepha_server0.RouteDescriptor<{
-    response: alepha21.TObject<{
-      prefix: alepha21.TOptional<alepha21.TString>;
-      links: alepha21.TArray<alepha21.TObject<{
-        name: alepha21.TString;
-        group: alepha21.TOptional<alepha21.TString>;
-        path: alepha21.TString;
-        method: alepha21.TOptional<alepha21.TString>;
-        requestBodyType: alepha21.TOptional<alepha21.TString>;
-        service: alepha21.TOptional<alepha21.TString>;
-      }>>;
-    }>;
-  }>;
-  /**
-   * Second API - Get schema for a specific API link.
-   *
-   * Note: Body/Response schema are not included in `links` API because it's TOO BIG.
-   * I mean for 150+ links, you got 50ms of serialization time.
-   */
-  readonly schema: alepha_server0.RouteDescriptor<{
-    params: alepha21.TObject<{
-      name: alepha21.TString;
-    }>;
-    response: alepha21.TRecord<string, alepha21.TAny>;
-  }>;
-  getSchemaByName(name: string, options?: GetApiLinksOptions): Promise<RequestConfigSchema>;
-  /**
-   * Retrieves API links for the user based on their permissions.
-   * Will check on local links and remote links.
-   */
-  getUserApiLinks(options: GetApiLinksOptions): Promise<ApiLinksResponse>;
-}
-interface GetApiLinksOptions {
-  user?: UserAccountToken;
-  authorization?: string;
-}
-//#endregion
-//#region src/server-links/index.d.ts
-declare module "alepha" {
-  interface State {
-    /**
-     * API links attached to the server request state.
-     *
-     * @see {@link ApiLinksResponse}
-     * @internal
-     */
-    "alepha.server.request.apiLinks"?: ApiLinksResponse;
-  }
-}
-/**
- * Provides server-side link management and remote capabilities for client-server interactions.
- *
- * The server-links module enables declarative link definitions using `$remote` and `$client` descriptors,
- * facilitating seamless API endpoint management and client-server communication. It integrates with server
- * security features to ensure safe and controlled access to resources.
- *
- * @see {@link $remote}
- * @see {@link $client}
- * @module alepha.server.links
- */
-declare const AlephaServerLinks: alepha21.Service<alepha21.Module>;
-//#endregion
-export { $client, $remote, AlephaServerLinks, ApiLink, ApiLinksResponse, ClientScope, FetchLinksOptions, GetApiLinksOptions, HttpClientLink, HttpVirtualClient, LinkProvider, RemoteDescriptor, RemoteDescriptorOptions, RemoteDescriptorProvider, ServerLinksProvider, ServerRemote, VirtualAction, apiLinkSchema, apiLinksResponseSchema };
-//# sourceMappingURL=index.d.cts.map