@types/sap__approuter 14.3.0

sap__approuter/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

sap__approuter/README.md

@@ -0,0 +1,15 @@
+# Installation
+> `npm install --save @types/sap__approuter`
+
+# Summary
+This package contains type definitions for @sap/approuter (https://www.npmjs.com/package/@sap/approuter).
+
+# Details
+Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/sap__approuter.
+
+### Additional Details
+ * Last updated: Tue, 21 Nov 2023 10:39:42 GMT
+ * Dependencies: [@types/http-server](https://npmjs.com/package/@types/http-server), [@types/node](https://npmjs.com/package/@types/node), [@types/verror](https://npmjs.com/package/@types/verror)
+
+# Credits
+These definitions were written by [Nico Blum](https://github.com/nbblum), and [Laurens von Assel](https://github.com/biolauri).

sap__approuter/index.d.ts

@@ -0,0 +1,389 @@
+/// <reference types="node" />
+
+import { EventEmitter } from "events";
+import { ClientRequest, IncomingMessage, ServerResponse } from "http";
+import { ServerOptions } from "https";
+
+import { ComSapXsappSchema_82 } from "./xs-app.schema";
+
+declare namespace approuter {
+    interface AfterRequestHandlerContext {
+        /** The request sent from client to application router */
+        incomingRequest: IncomingMessage;
+        /** The response that will be sent from application router to client */
+        incomingResponse: ServerResponse;
+        /** The request sent from application router to backend application */
+        outgoingRequest: ClientRequest;
+        /** The response that was received in application router from backend application */
+        outgoingResponse: IncomingMessage;
+    }
+
+    interface AppRouterIncomingMessage extends IncomingMessage {
+        /**
+         * A function that can be added to the request object - for example in a "first" or "beforeRequestHandler" extension.
+         * If exists, this function will be called by the standard application router after the standard backend response handling is completed.
+         *
+         * Note that this function is called after standard application router headers processing. Data piping is not modified.
+         * If an error is passed to done callback it will be just logged, piping process will not be stopped.
+         * Note that also in case of error the incomingResponse object should be returned.
+         *
+         * @example
+         *   var approuter = require('@sap/approuter');
+         *   var ar = approuter();
+         *   ar.first.use('/backend', function (req, res, next) {
+         *       req.afterRequestHandler = function(ctx, done){
+         *           if (ctx.outgoingResponse.statusCode === 200) {
+         *               let incomingResponse = ctx.incomingResponse;
+         *               incomingResponse.setHeader('header1', 'abc');
+         *               done(null, incomingResponse);
+         *           } else {
+         *               done('An error occurred in backend, returned status ' + ctx.outgoingResponse.statusCode, ctx.incomingResponse);
+         *           }
+         *       };
+         *       next();
+         *   });
+         *   ar.start();
+         * @param ctx - Context object for the request handler
+         * @param {AppRouterIncomingMessage~afterRequestHandlerCallback} done - A callback function that receives (optionally) and error and the modified incomingResponse
+         */
+        afterRequestHandler?: (
+            ctx: AfterRequestHandlerContext,
+            done: (error: Error | string | undefined | null, incomingResponse: ServerResponse) => void,
+        ) => void;
+
+        /**
+         * A function that can be added to the request object - for example in a "first" or "beforeRequestHandler" extension.
+         * If exists, this function will be called by the standard application router when a backend connection timeout occurs.
+         *
+         * @param req - the request object
+         * @param done - a callback function that doesn't return any parameter
+         */
+        backendTimeout?: (req: IncomingMessage, done: () => void) => void;
+
+        /**
+         * Callback for {@link afterRequestHandler}
+         *
+         * @param error - Error object in case of error
+         * @param incomingResponse - Modified incomingResponse
+         */
+    }
+
+    /**
+     * A handler for requests, called Middleware.
+     *
+     * @param request - Data of the incoming Request
+     * @param response - Object for the outgoing Response; can be manipulated to alter the response
+     * @param next - Call next to give control back to Application Router Middleware
+     */
+    type MiddlewareHandler = (request: AppRouterIncomingMessage, response: ServerResponse, next: () => void) => void;
+
+    interface Extensions {
+        /**
+         * Describes the middleware provided by this extension
+         * If a path is given, the handler is only invoked on these paths; otherwise it's invoked on all requests.
+         */
+        insertMiddleware: {
+            /** A MiddlewareSlot before the first application router middleware */
+            first?: Array<MiddlewareHandler | { path: string; handler: MiddlewareHandler }>;
+            /** A MiddlewareSlot before the standard application router request handling */
+            beforeRequestHandler?: Array<MiddlewareHandler | { path: string; handler: MiddlewareHandler }>;
+            /** A MiddlewareSlot before the standard application router error handling */
+            beforeErrorHandler?: Array<MiddlewareHandler | { path: string; handler: MiddlewareHandler }>;
+        };
+    }
+
+    type RouterConfig = unknown;
+
+    interface StartOptions {
+        /** A TCP port the application router will listen to */
+        port?: string;
+
+        /** The working directory for the application router, should contain the xs-app.json file */
+        workingDir?: string;
+
+        /** An array of extensions, each one is an object as defined in Application Router Extensions */
+        extensions?: Extensions[];
+
+        /**  An object representing the content which is usually put in xs-app.json file. If this property is present it will take precedence over the content of xs-app.json. */
+        xsAppConfig?: ComSapXsappSchema_82;
+
+        /**
+         * Options similar to [https.createServer](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener).
+         * If this property is present, application router will be started as an https server.
+         */
+        httpsConfig?: ServerOptions;
+
+        /**
+         * Provide custom access token
+         *
+         * @param request - Node request object
+         * @param {StartOptions~getTokenCallback} callback - Test
+         */
+        getToken?: (
+            request: AppRouterIncomingMessage,
+            callback: (error: Error | undefined | null, token: string) => void,
+        ) => void;
+
+        /**
+         * Provide custom routing configuration
+         *
+         * **Note**: When approuter is bound to html5 repository, you cannot provide getRouterConfig function.
+         *
+         * @param request - Node request object
+         * @param {StartOptions~getRouterConfigCallback} callback
+         */
+        getRouterConfig?: (
+            request: AppRouterIncomingMessage,
+            callback: (error: Error | undefined | null, routerConfig: RouterConfig | null | undefined) => void,
+        ) => void;
+
+        /**
+         * returns the session secret to be used by the application router for the signing of the session cookies.
+         */
+        getSessionSecret?: () => string;
+    }
+
+    interface RouterConfigOptions {
+        /**
+         * Value to replace $XSAPPNAME placeholder in scope names.
+         *
+         * If not provided, it will be taken from UAA service binding.
+         */
+        xsappname?: string;
+
+        /**
+         * An object representing the content which is usually put in xs-app.json file.
+         *
+         * **Note:** Only the typed configurations are taken into account from this property (the rest are taken from the xs-app.json file).
+         */
+        xsappConfig: Pick<ComSapXsappSchema_82, "welcomeFile" | "logout" | "routes" | "websockets" | "errorPage">;
+
+        /**
+         * An array containing the configuration of the backend destinations.
+         *
+         * If not provided, it will be taken from `destinations` environment variable.
+         */
+        destinations?: Array<{
+            name: string;
+            url: string;
+            forwardAuthToken: boolean;
+        }>;
+    }
+
+    interface MiddlewareSlot {
+        /**
+         * Inserts a request handling middleware in the current slot.
+         *
+         * @param handler - a middleware function to invoke
+         */
+        use(handler: MiddlewareHandler): MiddlewareSlot;
+
+        /**
+         * Inserts a request handling middleware in the current slot for the given path.
+         *
+         * @param path - handle only requests starting with this path
+         * @param handler - a middleware function to invoke
+         */
+        use(path: string, handler: MiddlewareHandler): MiddlewareSlot;
+    }
+
+    /**
+     * The application router uses a memory store as a session repository to provide the best runtime performance.
+     * However, it is not persisted, and it is not shared across multiple instances of the application router.
+     *
+     * Events
+     *  - update
+     *  - destroy
+     *  - timeout
+     */
+    interface MemoryStore extends EventEmitter {
+        /**
+         * returns the default session timeout in minutes.
+         */
+        getDefaultSessionTimeout(): number;
+
+        /**
+         * @param sessionId an unsigned session identifier
+         * @param callback function(error, session) a function that is called when the session object is retrieved from the internal session storage of the application router.
+         * error - an error object in case of an error, otherwise null
+         * timeout - time, in minutes, until the session times out
+         */
+        getSessionTimeout(sessionId: string, callback: (error: object | null, session: number) => void): void;
+
+        /**
+         * @param sessionId an unsigned session identifier
+         * @param callback a function that is called when the session object is retrieved from the internal session storage of the application router.
+         * error - an error object in case of an error, otherwise null
+         * session - the session object
+         * id - session identifier, immutable
+         */
+        get(sessionId: string, callback: (error: object | null, session: number) => void): void;
+
+        /**
+         * @param sessionId an unsigned session identifier
+         * @param sessionString a session object serialized to string
+         * @param timeout a timestamp in milliseconds, after which the session should be automatically invalidated
+         * @param callback  a function that is called after the session is saved in the internal session storage of the application router
+         */
+        set(sessionId: string, sessionString: string, timeout: number, callback: () => void): void;
+
+        /**
+         * @param sessionId an unsigned session identifier
+         * @param callback  function(currentSession) function, which returns session object. Callback function may modify and return current session object or create and return brand new session object
+         * currentSession - current session object
+         * @param resetTimeout a boolean that indicates whether to reset the session timeout
+         */
+        update(sessionId: string, callback: (currentSession: object) => void, resetTimeout: boolean): void;
+
+        /**
+         * @param sessionId an unsigned session identifier
+         * @param callback a function that is called after the session is destroyed in the internal session storage of the application router
+         */
+        destroy(sessionId: string, callback: () => void): void;
+
+        /**
+         * Emitted when a user session has been updated.
+         *
+         * @param event
+         */
+        on(event: "update", listener: (sessionId: string) => void): this;
+    }
+
+    type SessionStore = MemoryStore;
+
+    /**
+     * SAP Application Router
+     *
+     * For full help, please consult the README file in @sap/approuter (the source npm package) or
+     * https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/LATEST/en-US/050d87a61faa4fb88f687abd7bdf16ce.html
+     *
+     * These types (and their tests) are mostly extracted from the above mentioned README file and `doc/extending.md`
+     * in @sap/approuter (the source npm package). If some types are incorrect or missing, please open up an issue at
+     * {@link https://github.com/DefinitelyTyped/DefinitelyTyped}, or, even better, add them by yourself via a Pull Request.
+     *
+     * ## Command Parser
+     * The {@link cmdParser} property is set to a {@link Command} instance when instantiating an Approuter. It is possible
+     * to disable this feature by setting {@link cmdParser} to false. To do this typesafe, you have to use
+     * `Approuter<false>` as a type when creating the Approuter instance.
+     * @example
+     *   const ar = new Approuter<false>();
+     *   ar.cmdParser = false;
+     */
+    interface Approuter extends EventEmitter {
+        /**
+         * A {@link MiddlewareSlot} before the first application router middleware
+         */
+        first: MiddlewareSlot;
+
+        /**
+         * A {@link MiddlewareSlot} before the standard application router request handling
+         */
+        beforeRequestHandler: MiddlewareSlot;
+
+        /**
+         * A {@link MiddlewareSlot} before the standard application router error handling
+         */
+        beforeErrorHandler: MiddlewareSlot;
+
+        /**
+         * **Note**: the cmdParser is currently not typed, feel free to create a pr and add the missing types
+         *
+         * By default the application router handles its command line parameters, but you can customize that too.
+         *
+         * An _approuter_ instance provides the property `cmdParser` that is a [commander](https://github.com/tj/commander.js/) instance.
+         * It is configured with the standard application router command line options.
+         *
+         * To completely disable the command line option handling in the application router, reset the following property: `ar.cmdParser = false;`
+         *
+         * @example
+         *   var approuter = require('@sap/approuter');
+         *
+         *   var ar = approuter();
+         *
+         *   var params = ar.cmdParser
+         *   // add here custom command line options if needed
+         *     .option('-d, --dummy', 'A dummy option')
+         *     .parse(process.argv);
+         *
+         *   console.log('Dummy option:', params.dummy);
+         */
+        cmdParser: never;
+
+        /**
+         * Starts the application router with the given options.
+         *
+         * @param options - Customize the Approuter with some configurations
+         * @param callback - Is invoked when the application router has started or an error has occurred. If not provided and an error occurs (e.g. the port is busy), the application will abort.
+         */
+        start(options?: StartOptions, callback?: (err: Error | undefined | null) => void): void;
+
+        /**
+         * Stops the application router.
+         *
+         * @param callback - Is invoked when the application router has stopped or an error has occurred.
+         */
+        close(callback?: (error: Error | undefined | null) => void): void;
+
+        /**
+         * Prepares the routing configuration to be used by the application router. As part of this, the application router validates the given options.
+         * This function can be used at any point in runtime to create additional routing configurations.
+         *
+         * **Note**: This function can be called only after {@link start} function.
+         *
+         * @param options - Router configurations
+         * @param {Approuter~createRouterConfigCallback} callback
+         */
+        createRouterConfig(
+            options: RouterConfigOptions,
+            callback: (error: Error | undefined | null, routerConfig: RouterConfig) => void,
+        ): void;
+
+        /**
+         * Calculates tenant-specific UAA configuration.
+         *
+         * @param request - node request object used to identify the tenant
+         * @param uaaOptions - UAA options as provided in service binding
+         * @param {Approuter~resolveUaaConfigCallback} callback
+         */
+        resolveUaaConfig(
+            request: AppRouterIncomingMessage,
+            uaaOptions: any,
+            callback: (error: Error | undefined | null, tenantUaaOptions: any) => void,
+        ): void;
+
+        /**
+         * returns SessionStore instance.
+         */
+        getSessionStore(): SessionStore;
+
+        /**
+         * Emitted when a new user session is created.
+         *
+         * @param event
+         * @param {Approuter~onLoginLogoutCallback} listener
+         */
+        on(event: "login", listener: (session: { id: string }) => void): this;
+
+        /**
+         * Emitted when a new user session has been updated.
+         *
+         * @param event
+         * @param {Approuter~onLoginLogoutCallback} listener
+         */
+        on(event: "update", listener: (sessionId: string, timeout: number) => void): this;
+
+        /**
+         * Emitted when a user session has expired or a user has requested to log out.
+         *
+         * @param event
+         * @param {Approuter~onLoginLogoutCallback} listener
+         */
+        // Disabled for better JSDocs
+        // tslint:disable-next-line:unified-signatures
+        on(event: "logout", listener: (session: { id: string }) => void): this;
+    }
+}
+
+declare function approuter(): approuter.Approuter;
+
+export = approuter;

sap__approuter/package.json

@@ -0,0 +1,34 @@
+{
+    "name": "@types/sap__approuter",
+    "version": "14.3.0",
+    "description": "TypeScript definitions for @sap/approuter",
+    "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/sap__approuter",
+    "license": "MIT",
+    "contributors": [
+        {
+            "name": "Nico Blum",
+            "githubUsername": "nbblum",
+            "url": "https://github.com/nbblum"
+        },
+        {
+            "name": "Laurens von Assel",
+            "githubUsername": "biolauri",
+            "url": "https://github.com/biolauri"
+        }
+    ],
+    "main": "",
+    "types": "index.d.ts",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/DefinitelyTyped/DefinitelyTyped.git",
+        "directory": "types/sap__approuter"
+    },
+    "scripts": {},
+    "dependencies": {
+        "@types/http-server": "*",
+        "@types/node": "*",
+        "@types/verror": "*"
+    },
+    "typesPublisherContentHash": "6e90fefa56f7582b3db68e3977022dbabc5b4038b85d7cf8178a5fd1f8d6d89c",
+    "typeScriptVersion": "4.5"
+}

sap__approuter/xs-app.schema.d.ts

@@ -0,0 +1,100 @@
+// Original file: https://json.schemastore.org/xs-app.json
+// Online converter: https://bcherny.github.io/json-schema-to-typescript-browser/
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+
+export type SourceSchema =
+    | string
+    | {
+        path: string;
+        matchCase?: boolean;
+    };
+export type ScopesSchema =
+    | string
+    | [string, ...string[]]
+    | {
+        GET?: ScopeTemplate;
+        POST?: ScopeTemplate;
+        HEAD?: ScopeTemplate;
+        PUT?: ScopeTemplate;
+        DELETE?: ScopeTemplate;
+        TRACE?: ScopeTemplate;
+        PATCH?: ScopeTemplate;
+        OPTIONS?: ScopeTemplate;
+        CONNECT?: ScopeTemplate;
+        default?: ScopeTemplate;
+    };
+export type ScopeTemplate = string | [string, ...string[]];
+
+/**
+ * Application Router Configuration Schema
+ */
+export interface ComSapXsappSchema_82 {
+    welcomeFile?: string;
+    authenticationMethod?: "none" | "route";
+    sessionTimeout?: number;
+    pluginMetadataEndpoint?: string;
+    routes?: Array<{
+        source: SourceSchema;
+        httpMethods?: [
+            "DELETE" | "GET" | "HEAD" | "OPTIONS" | "POST" | "PUT" | "TRACE" | "PATCH",
+            ...Array<"DELETE" | "GET" | "HEAD" | "OPTIONS" | "POST" | "PUT" | "TRACE" | "PATCH">,
+        ];
+        target?: string;
+        destination?: string;
+        localDir?: string;
+        csrfProtection?: boolean;
+        service?: string;
+        endpoint?: string;
+        authenticationType?: "xsuaa" | "basic" | "none";
+        identityProvider?: string;
+        scope?: ScopesSchema;
+        replace?: {
+            pathSuffixes: string[];
+            vars?: string[];
+            services?: {
+                [k: string]: unknown;
+            };
+        };
+        cacheControl?: string;
+    }>;
+    destinations?: {
+        [k: string]: {
+            logoutPath?: string;
+            logoutMethod?: "PUT" | "POST" | "GET";
+        };
+    };
+    services?: {
+        [k: string]: {
+            endpoint?: string;
+            logoutPath?: string;
+            logoutMethod?: "PUT" | "POST" | "GET";
+        };
+    };
+    logout?: {
+        logoutEndpoint?: string;
+        logoutPage?: string;
+    };
+    login?: {
+        callbackEndpoint: string;
+    };
+    whitelistService?: {
+        endpoint: string;
+    };
+    compression?: {
+        enabled?: boolean;
+        minSize?: number;
+    };
+    websockets?: {
+        enabled: boolean;
+    };
+    errorPage?: Array<{
+        status: number | [number, ...number[]];
+        file: string;
+        [k: string]: unknown;
+    }>;
+    [k: string]: unknown;
+}