@kurdel/common 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Andrii Sorokin
+
+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.

package/README.md

@@ -0,0 +1,24 @@
+# @kurdel/common
+
+Shared TypeScript types, interfaces, and utilities used by Kurdel packages.
+Application code normally receives this package transitively through the
+framework packages that depend on it.
+
+## Installation
+
+```bash
+npm install @kurdel/common@beta
+```
+
+## Exports
+
+The package exposes common HTTP types, authentication user contracts, JSON
+loading helpers, and URL utilities from its main entry point.
+
+## Requirements
+
+Node.js 20.19+, 22.12+, or 24+.
+
+## License
+
+MIT © Andrii Sorokin

package/lib/auth-user.d.ts

@@ -0,0 +1,34 @@
+/**
+ * ## AuthUser
+ *
+ * Unified representation of an authenticated identity within the Kurdel runtime.
+ *
+ * Produced exclusively by authentication strategies.
+ * Used later by authorization middleware to determine access rights.
+ *
+ * Properties:
+ * - `id` — public stable identity of the user (string or number).
+ * - `roles` — zero or more logical roles (e.g., `"admin"`, `"user"`, `"system"`).
+ * - Additional fields may be attached by strategies (JWT payload, profile data, etc.).
+ *
+ * @remarks
+ * The runtime never interprets extra properties — they are passed through
+ * transparently and may be used by controllers or custom middleware.
+ */
+export interface AuthUser {
+    id: string | number;
+    roles: string[];
+    [key: string]: unknown;
+}
+/** Metadata about the credential used for the current authentication. */
+export interface AuthCredential {
+    type: string;
+    id?: string;
+}
+/** Authentication state attached to a request after a strategy succeeds. */
+export interface AuthContext<TUser extends AuthUser = AuthUser> {
+    user: TUser;
+    strategy: string;
+    credential?: AuthCredential;
+    claims?: Record<string, unknown>;
+}

package/lib/auth-user.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth-user.js.map

package/lib/auth-user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-user.js","sourceRoot":"","sources":["../src/auth-user.ts"],"names":[],"mappings":""}

package/lib/http-response-extended.d.ts

@@ -0,0 +1,13 @@
+import type { HttpResponse } from './interfaces.js';
+/**
+ * Extended interface for platform adapters (Node, Express, etc.)
+ * that expose header manipulation methods.
+ */
+export interface HttpResponseWithHeaders extends HttpResponse {
+    /** Set a response header (platform-specific) */
+    setHeader(name: string, value: string): void;
+    /** Retrieve a response header */
+    getHeader(name: string): string | undefined;
+    /** Optional shorthand for MIME type */
+    type?(mime: string): this;
+}

package/lib/http-response-extended.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=http-response-extended.js.map

package/lib/http-response-extended.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-response-extended.js","sourceRoot":"","sources":["../src/http-response-extended.ts"],"names":[],"mappings":""}

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './interfaces.js';
+export * from './auth-user.js';
+export * from './http-response-extended.js';
+export * from './json-loader.js';
+export * from './url.js';

package/lib/index.js

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './interfaces.js';
+export * from './auth-user.js';
+export * from './http-response-extended.js';
+export * from './json-loader.js';
+export * from './url.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC"}

package/lib/interfaces.d.ts

@@ -0,0 +1,28 @@
+/** A minimal, platform-independent HTTP request abstraction. */
+export interface HttpRequest {
+    method: string;
+    url: string;
+    headers?: Record<string, string | string[]>;
+    body?: unknown;
+    query: Record<string, string | string[]>;
+    params?: Record<string, string>;
+}
+/** A minimal, platform-independent HTTP response abstraction. */
+export interface HttpResponse {
+    /** Sends a complete response body (string, Buffer, or object). */
+    send(body?: any): void;
+    /** Sends a JSON response with correct content type. */
+    json(body: unknown): void;
+    /** Sets the HTTP status code. */
+    status(code: number): this;
+    /** Optional shorthand for redirection. */
+    redirect(status: number, location: string): void;
+    /** Write a data chunk to the response stream. */
+    write?(chunk: any): void;
+    /** End the response stream (optional final data chunk). */
+    end?(chunk?: any): void;
+    /** Marks the response as already sent. */
+    sent: boolean;
+    /** Underlying native platform response (optional). */
+    raw?: unknown;
+}

package/lib/interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=interfaces.js.map

package/lib/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":""}

package/lib/json-loader.d.ts

@@ -0,0 +1,3 @@
+export declare class JSONLoader {
+    load(filePath: string): any;
+}

package/lib/json-loader.js

@@ -0,0 +1,15 @@
+import fs from 'fs';
+export class JSONLoader {
+    load(filePath) {
+        try {
+            const rawData = fs.readFileSync(filePath, 'utf8');
+            const config = JSON.parse(rawData);
+            return config;
+        }
+        catch (err) {
+            console.error(`Error reading config file: ${err}`);
+            throw new Error(`Failed to read config file: ${filePath}`);
+        }
+    }
+}
+//# sourceMappingURL=json-loader.js.map

package/lib/json-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-loader.js","sourceRoot":"","sources":["../src/json-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,MAAM,OAAO,UAAU;IACrB,IAAI,CAAC,QAAgB;QACnB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAClD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACnC,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,8BAA8B,GAAG,EAAE,CAAC,CAAC;YACnD,MAAM,IAAI,KAAK,CAAC,+BAA+B,QAAQ,EAAE,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;CACF"}

package/lib/types.d.ts

@@ -0,0 +1 @@
+export type Newable<T> = new (...args: any[]) => T;

package/lib/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/lib/url.d.ts

@@ -0,0 +1,11 @@
+/** Default base used when constructing internal URLs. */
+export declare const DEFAULT_INTERNAL_BASE = "http://internal";
+/** Key → string or array of strings (for repeated query params). */
+export type QueryMap = Record<string, string | string[]>;
+/**
+ * Build a URL from a string path or an existing URL.
+ * Never reads Node.js request types; pure and platform-agnostic.
+ */
+export declare function buildURL(input: string | URL, base?: string): URL;
+/** Convert URLSearchParams into a multi-value map. */
+export declare function toQuery(u: URL): QueryMap;

package/lib/url.js

@@ -0,0 +1,27 @@
+/** Default base used when constructing internal URLs. */
+export const DEFAULT_INTERNAL_BASE = 'http://internal';
+/**
+ * Build a URL from a string path or an existing URL.
+ * Never reads Node.js request types; pure and platform-agnostic.
+ */
+export function buildURL(input, base = DEFAULT_INTERNAL_BASE) {
+    if (input instanceof URL)
+        return input;
+    const path = input || '/';
+    return new URL(path, base);
+}
+/** Convert URLSearchParams into a multi-value map. */
+export function toQuery(u) {
+    const out = {};
+    u.searchParams.forEach((value, key) => {
+        if (key in out) {
+            const prev = out[key];
+            out[key] = Array.isArray(prev) ? [...prev, value] : [prev, value];
+        }
+        else {
+            out[key] = value;
+        }
+    });
+    return out;
+}
+//# sourceMappingURL=url.js.map

package/lib/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../src/url.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,MAAM,CAAC,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AAKvD;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAmB,EAAE,OAAe,qBAAqB;IAChF,IAAI,KAAK,YAAY,GAAG;QAAE,OAAO,KAAK,CAAC;IACvC,MAAM,IAAI,GAAG,KAAK,IAAI,GAAG,CAAC;IAC1B,OAAO,IAAI,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,OAAO,CAAC,CAAM;IAC5B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACpC,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;YACf,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACtB,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAc,EAAE,KAAK,CAAC,CAAC;QAC9E,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@kurdel/common",
+  "version": "0.1.0-beta.1",
+  "description": "Shared types and utilities for Kurdel packages",
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "prepack": "npm run build",
+    "test": "echo \"No tests yet\"",
+    "clean": "rimraf lib ../../.cache/tsconfig.common.build.tsbuildinfo",
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "build:force": "npm run clean && tsc -p tsconfig.build.json --force && tsc-alias -p tsconfig.build.json"
+  },
+  "keywords": [
+    "kurdel",
+    "framework",
+    "utilities",
+    "typescript"
+  ],
+  "author": "Andrii Sorokin",
+  "license": "MIT",
+  "engines": {
+    "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ignorantic/kurdel.git",
+    "directory": "packages/common"
+  },
+  "homepage": "https://github.com/ignorantic/kurdel/tree/main/packages/common#readme",
+  "bugs": {
+    "url": "https://github.com/ignorantic/kurdel/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0",
+    "rimraf": "^3.0.2",
+    "tsc-alias": "^1.8.16"
+  }
+}