jskelet 0.5.4 → 0.6.0

package/types/server/image-optimizer.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @returns {import('../config/index.js').ImagesRemoteConfig | null}
+ */
+export declare function getRemoteImages(): import('../config/index.js').ImagesRemoteConfig | null;
+/**
+ * Mutlak http(s) URL mi ve allowHosts'ta mı.
+ * @param {string} src
+ * @returns {URL | null}
+ */
+export declare function parseAllowedRemoteUrl(src: string): URL | null;
+/**
+ * Host allowlist + literal private IP; redirect hop'larında da kullanılır.
+ *
+ * @param {URL} url
+ * @param {string[]} allowHosts
+ * @returns {boolean}
+ */
+export declare function isRemoteUrlShapeAllowed(url: URL, allowHosts: string[]): boolean;
+/**
+ * Hostname'i çözümleyip private IP'ye düşüyorsa reddet (DNS rebinding
+ * savunması; TOCTOU kalır ama check-time private resolve yakalanır).
+ *
+ * @param {string} hostname
+ * @returns {Promise<boolean>} true = güvenli
+ */
+export declare function assertResolvedHostSafe(hostname: string): Promise<boolean>;
+/**
+ * @param {string} hostname
+ * @param {string[]} allowHosts
+ * @returns {boolean}
+ */
+export declare function isHostAllowed(hostname: string, allowHosts: string[]): boolean;
+/**
+ * Literal private / link-local / loopback host'ları reddet (SSRF).
+ * Allowlist asıl koruma; bu ek bir savunma katmanı.
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+export declare function isBlockedAddress(hostname: string): boolean;
+/**
+ * Optimizer URL'si üret. `image()` ve elle URL kuran uygulamalar için.
+ * @param {string} src Uzak görsel URL'si
+ * @param {{ width: number, quality?: number }} options
+ * @returns {string | null} Allowlist dışıysa null
+ */
+export declare function remoteImageUrl(src: string, options: {
+    width: number;
+    quality?: number;
+}): string | null;
+/**
+ * @param {number} width
+ * @param {number} maxWidth
+ * @returns {number}
+ */
+export declare function clampWidth(width: number, maxWidth: number): number;
+/**
+ * Görüntülenen genişliğe göre srcset adayları (1x + 2x + config widths).
+ * @param {number} displayWidth
+ * @param {number[]} widths
+ * @param {number} maxWidth
+ * @returns {number[]}
+ */
+export declare function srcsetWidths(displayWidth: number, widths: number[], maxWidth: number): number[];
+/**
+ * @param {import('express').Express} app
+ * @returns {Promise<void>}
+ */
+export declare function mountImageOptimizer(app: import('express').Express): Promise<void>;

package/types/server/logs/access-middleware.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @param {{ basePath?: string }} [options]
+ * @returns {import('express').RequestHandler}
+ */
+export declare function accessLogMiddleware(options?: {
+    basePath?: string;
+}): import('express').RequestHandler;

package/types/server/logs/file-sink.d.ts

@@ -0,0 +1,17 @@
+export type LogSink = {
+    write: (entry: Record<string, unknown>) => Promise<void>;
+    flush: () => Promise<void>;
+    close: () => Promise<void>;
+};
+/**
+ * @typedef {{ write: (entry: Record<string, unknown>) => Promise<void>,
+ *   flush: () => Promise<void>, close: () => Promise<void> }} LogSink
+ */
+/**
+ * @param {{ root: string, dir: string }} options
+ * @returns {LogSink}
+ */
+export declare function createFileSink(options: {
+    root: string;
+    dir: string;
+}): LogSink;

package/types/server/logs/pipeline.d.ts

@@ -0,0 +1,37 @@
+export type LogsConfig = import('../../config/index.js').LogsConfig;
+export type ResolvedConfig = import('../../config/index.js').ResolvedConfig;
+export type LogSink = import('./file-sink.js').LogSink;
+/**
+ * Access middleware mount edilmeli mi?
+ *
+ * Dev'de yalnızca console isteniyorsa mount edilmez — HTML satırlarını
+ * zaten devtools basıyor; çift kayıt olmasın. Sink açıksa ya da production
+ * console access log istiyorsa mount edilir.
+ *
+ * @param {LogsConfig} logs
+ * @returns {boolean}
+ */
+export declare function shouldMountAccessLog(logs: LogsConfig): boolean;
+/**
+ * @param {ResolvedConfig} config
+ * @returns {Promise<{ accessLog: boolean }>}
+ */
+export declare function configureLogs(config: ResolvedConfig): Promise<{
+    accessLog: boolean;
+}>;
+/**
+ * Access middleware ve `log.subscribe` ortak giriş noktası.
+ *
+ * @param {Record<string, unknown>} raw
+ */
+export declare function acceptLogEntry(raw: Record<string, unknown>): void;
+/**
+ * Kapanışta buffer'ları boşaltır.
+ *
+ * @returns {Promise<void>}
+ */
+export declare function flushLogs(): Promise<void>;
+/**
+ * @returns {Promise<void>}
+ */
+export declare function closeLogs(): Promise<void>;

package/types/server/logs/s3-put.d.ts

@@ -0,0 +1,85 @@
+export type AwsCredentials = {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string | null;
+};
+export type PutObjectInput = {
+    bucket: string;
+    key: string;
+    body: string | Buffer;
+    region: string;
+    endpoint?: string | null;
+    credentials: AwsCredentials;
+    now?: Date;
+};
+/**
+ * @param {string | Buffer} data
+ * @returns {string}
+ */
+export declare function sha256Hex(data: string | Buffer): string;
+/**
+ * @param {Date} date
+ * @returns {{ amzDate: string, dateStamp: string }}
+ */
+export declare function formatAmzDates(date: Date): {
+    amzDate: string;
+    dateStamp: string;
+};
+/**
+ * @param {string} secretAccessKey
+ * @param {string} dateStamp
+ * @param {string} region
+ * @param {string} service
+ * @returns {Buffer}
+ */
+export declare function deriveSigningKey(secretAccessKey: string, dateStamp: string, region: string, service: string): Buffer;
+/**
+ * @param {{ method: string, canonicalUri: string, canonicalQuerystring?: string,
+ *   headers: Record<string, string>, payloadHash: string }} parts
+ * @returns {{ canonicalRequest: string, signedHeaders: string }}
+ */
+export declare function buildCanonicalRequest(parts: {
+    method: string;
+    canonicalUri: string;
+    canonicalQuerystring?: string;
+    headers: Record<string, string>;
+    payloadHash: string;
+}): {
+    canonicalRequest: string;
+    signedHeaders: string;
+};
+/**
+ * @param {{ amzDate: string, dateStamp: string, region: string, service: string,
+ *   canonicalRequest: string }} parts
+ * @returns {string}
+ */
+export declare function buildStringToSign(parts: {
+    amzDate: string;
+    dateStamp: string;
+    region: string;
+    service: string;
+    canonicalRequest: string;
+}): string;
+/**
+ * URI path encode (S3 key segment'leri). `/` korunur.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export declare function encodeS3Path(value: string): string;
+/**
+ * PutObject isteğini imzalar; ağ çağrısı yapmaz — test edilebilir olsun diye.
+ *
+ * @param {PutObjectInput} input
+ * @returns {{ url: string, headers: Record<string, string>, body: Buffer }}
+ */
+export declare function buildSignedPutObject(input: PutObjectInput): {
+    url: string;
+    headers: Record<string, string>;
+    body: Buffer;
+};
+/**
+ * @param {PutObjectInput} input
+ * @returns {Promise<void>}
+ */
+export declare function putObject(input: PutObjectInput): Promise<void>;

package/types/server/logs/s3-sink.d.ts

@@ -0,0 +1,26 @@
+import { putObject } from "./s3-put.js";
+export type LogSink = import('./file-sink.js').LogSink;
+export type AwsCredentials = import('./s3-put.js').AwsCredentials;
+/**
+ * @typedef {import('./file-sink.js').LogSink} LogSink
+ * @typedef {import('./s3-put.js').AwsCredentials} AwsCredentials
+ */
+/**
+ * @param {{ bucket: string, prefix: string, region: string,
+ *   endpoint?: string | null, credentials: AwsCredentials,
+ *   flushIntervalMs: number, maxBatch: number,
+ *   put?: typeof putObject }} options
+ * @returns {LogSink & { pendingCount: () => number }}
+ */
+export declare function createS3Sink(options: {
+    bucket: string;
+    prefix: string;
+    region: string;
+    endpoint?: string | null;
+    credentials: AwsCredentials;
+    flushIntervalMs: number;
+    maxBatch: number;
+    put?: typeof putObject;
+}): LogSink & {
+    pendingCount: () => number;
+};

package/types/server/metadata.d.ts

@@ -0,0 +1,38 @@
+export type Metadata = {
+    title?: string;
+    /**
+     * `"%s | Site"` — `title` buna gömülür.
+     */
+    titleTemplate?: string;
+    description?: string;
+    /**
+     * Mutlak ya da göreli URL.
+     */
+    canonical?: string;
+    /**
+     * Göreli canonical'ı mutlaklaştırmak için.
+     */
+    siteUrl?: string;
+    robots?: {
+        index?: boolean;
+        follow?: boolean;
+    };
+    locale?: string;
+    /**
+     * `{ title, description, url, type, siteName, image, imageWidth, imageHeight }`
+     */
+    openGraph?: object;
+    /**
+     * `{ card, site, creator, title, description, image }`
+     */
+    twitter?: object;
+    /**
+     * Olduğu gibi basılacak ham etiketler.
+     */
+    extraTags?: string[];
+};
+/**
+ * @param {Metadata} [metadata]
+ * @returns {string}
+ */
+export declare function renderHeadMeta(metadata?: Metadata): string;

package/types/server/middleware/compression.d.ts

@@ -0,0 +1,17 @@
+/**
+ * İçeriği bir kez sıkıştırıp saklamak isteyen çağıranlar için (HTML cache).
+ *
+ * @param {string | undefined} acceptEncoding
+ * @returns {"br" | "gzip" | null}
+ */
+export declare function negotiateEncoding(acceptEncoding: string | undefined): "br" | "gzip" | null;
+/**
+ * @param {string} text
+ * @param {"br" | "gzip"} encoding
+ * @returns {Promise<Buffer>}
+ */
+export declare function encodeText(text: string, encoding: "br" | "gzip"): Promise<Buffer>;
+/**
+ * @returns {import('express').RequestHandler}
+ */
+export declare function compression(): import('express').RequestHandler;

package/types/server/middleware/csrf.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @returns {import('express').RequestHandler}
+ */
+export declare function csrf(): import('express').RequestHandler;

package/types/server/middleware/dev-gate.d.ts

@@ -0,0 +1,2 @@
+/** @returns {import('express').RequestHandler} */
+export declare function devGate(): import('express').RequestHandler;

package/types/server/middleware/headers.d.ts

@@ -0,0 +1,2 @@
+/** @returns {import('express').RequestHandler} */
+export declare function headersMiddleware(): import('express').RequestHandler;

package/types/server/middleware/redirects.d.ts

@@ -0,0 +1,2 @@
+/** @returns {import('express').RequestHandler} */
+export declare function redirects(): import('express').RequestHandler;

package/types/server/middleware/static-precompressed.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @param {string} publicDir
+ * @returns {import('express').RequestHandler}
+ */
+export declare function staticPrecompressed(publicDir: string): import('express').RequestHandler;

package/types/server/middleware/trailing-slash.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Bu yola trailing slash dayatılmamalı mı.
+ *
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+export declare function skipTrailingSlash(pathname: string): boolean;
+/**
+ * @returns {import('express').RequestHandler}
+ */
+export declare function trailingSlash(): import('express').RequestHandler;

package/types/server/middleware/upstream-proxy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Hedefi isteğe göre hesaplayan proxy üretir. `resolveTarget` fırlatırsa
+ * istek proxy'lenmez ve zincire devam eder — hedef origin yapılandırılmamış
+ * bir kurulumda 500 yerine normal 404 almak daha doğru.
+ *
+ * @param {(req: import('express').Request) => string} resolveTarget
+ * @returns {import('express').RequestHandler}
+ */
+export declare function createProxy(resolveTarget: (req: import('express').Request) => string): import('express').RequestHandler;
+/**
+ * Config'teki `rewrites()` kuralları.
+ *
+ * Hedef mutlaksa (http/https) istek proxy ile dışa taşınır; göreliyse
+ * yalnızca `req.url` değiştirilir ve istek kendi route tablosunda devam eder.
+ * İki faz var: `beforeFiles` statik dosyalardan önce, `afterFiles` statik
+ * denendikten sonra sayfalardan önce.
+ *
+ * @param {"beforeFiles" | "afterFiles"} phase
+ * @returns {import('express').RequestHandler}
+ */
+export declare function configRewrites(phase: "beforeFiles" | "afterFiles"): import('express').RequestHandler;

package/types/server/og-image.d.ts

@@ -0,0 +1,149 @@
+/** Sosyal kartlar için yaygın boyut (Facebook / X / LinkedIn). */
+export declare const OG_SIZE: Readonly<{
+    width: 1200;
+    height: 630;
+}>;
+export type OgCardOptions = {
+    title?: string;
+    description?: string;
+    siteName?: string;
+    /**
+     * Düz SVG rengi (`#0f172a`)
+     */
+    background?: string;
+    /**
+     * Ana metin rengi
+     */
+    color?: string;
+    /**
+     * Açıklama / site adı
+     */
+    mutedColor?: string;
+    /**
+     * Sol şerit rengi
+     */
+    accent?: string;
+};
+export type OgImageOptions = OgCardOptions & {
+    svg?: string;
+    width?: number;
+    height?: number;
+    format?: 'png' | 'svg';
+    cacheControl?: string;
+};
+export type OgImageResult = {
+    body: Buffer;
+    contentType: string;
+    width: number;
+    height: number;
+};
+/**
+ * @typedef {object} OgCardOptions
+ * @property {string} [title]
+ * @property {string} [description]
+ * @property {string} [siteName]
+ * @property {string} [background] Düz SVG rengi (`#0f172a`)
+ * @property {string} [color] Ana metin rengi
+ * @property {string} [mutedColor] Açıklama / site adı
+ * @property {string} [accent] Sol şerit rengi
+ */
+/**
+ * @typedef {OgCardOptions & {
+ *   svg?: string,
+ *   width?: number,
+ *   height?: number,
+ *   format?: 'png' | 'svg',
+ *   cacheControl?: string,
+ * }} OgImageOptions
+ */
+/**
+ * @typedef {object} OgImageResult
+ * @property {Buffer} body
+ * @property {string} contentType
+ * @property {number} width
+ * @property {number} height
+ */
+/**
+ * XML metin kaçışı — kullanıcı başlığı SVG'ye gömülür.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export declare function escapeXml(value: unknown): string;
+/**
+ * Kelime sınırında satır kır. Uzun kelime kesilir; taşan içerik son satırda `…`.
+ * @param {string} text
+ * @param {number} maxChars
+ * @param {number} maxLines
+ * @returns {string[]}
+ */
+export declare function wrapText(text: string, maxChars: number, maxLines: number): string[];
+/**
+ * Hazır kart SVG'si. Uygulama kendi SVG'sini vermek isterse `svg` kullanır.
+ * @param {OgCardOptions & { width?: number, height?: number }} options
+ * @returns {string}
+ */
+export declare function buildOgSvg(options?: OgCardOptions & {
+    width?: number;
+    height?: number;
+}): string;
+/**
+ * SVG veya kart alanlarından PNG/SVG gövde üretir.
+ * @param {OgImageOptions} [options]
+ * @returns {Promise<OgImageResult>}
+ */
+export declare function ogImage(options?: OgImageOptions): Promise<OgImageResult>;
+/**
+ * Express yanıtına OG görseli basar.
+ * @param {import('express').Response} res
+ * @param {OgImageOptions} [options]
+ * @returns {Promise<OgImageResult>}
+ */
+export declare function sendOgImage(res: import('express').Response, options?: OgImageOptions): Promise<OgImageResult>;
+/**
+ * Next `opengraph-image` route handler'ına yakın Express sarmalayıcı.
+ *
+ * Factory `null` dönerse veya `notFound()` fırlatırsa 404.
+ *
+ * @param {(ctx: { params: Record<string, string>, query: import('express').Request['query'], req: import('express').Request }) =>
+ *   OgImageOptions | null | Promise<OgImageOptions | null>} factory
+ * @param {OgImageOptions} [defaults] Her istekte birleşen varsayılanlar
+ * @returns {import('express').RequestHandler}
+ */
+export declare function ogHandler(factory: (ctx: {
+    params: Record<string, string>;
+    query: import('express').Request['query'];
+    req: import('express').Request;
+}) => OgImageOptions | null | Promise<OgImageOptions | null>, defaults?: OgImageOptions): import('express').RequestHandler;
+/**
+ * Next.js `new ImageResponse(...)` DX'si. JSX yok — ilk argüman SVG string
+ * veya kart alanları nesnesi.
+ *
+ * @example
+ * ```js
+ * return new ImageResponse(
+ *   { title: post.title, description: post.excerpt, siteName: "Blog" },
+ *   { width: 1200, height: 630 },
+ * );
+ * // handler içinde: await image.send(res)
+ * ```
+ */
+export declare class ImageResponse {
+    #private;
+    /**
+     * @param {string | OgCardOptions} element
+     * @param {Omit<OgImageOptions, keyof OgCardOptions | 'svg'> & { width?: number, height?: number }} [init]
+     */
+    constructor(element: string | OgCardOptions, init?: Omit<OgImageOptions, keyof OgCardOptions | 'svg'> & {
+        width?: number;
+        height?: number;
+    });
+    /** @returns {OgImageOptions} */
+    get options(): OgImageOptions;
+    /** @returns {Promise<OgImageResult>} */
+    buffer(): Promise<OgImageResult>;
+    /**
+     * @param {import('express').Response} res
+     * @returns {Promise<OgImageResult>}
+     */
+    send(res: import('express').Response): Promise<OgImageResult>;
+}

package/types/server/port-guard.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `netstat -ano -p tcp` çıktısından LISTENING PID'lerini çıkarır.
+ * `3000` ile `30001` karışmasın diye porttan sonra rakam olmamalı.
+ *
+ * @param {string} stdout
+ * @param {number} port
+ * @returns {number[]}
+ */
+export declare function parseWindowsNetstat(stdout: string, port: number): number[];
+/**
+ * `lsof -t` çıktısı: satır başına bir PID.
+ *
+ * @param {string} stdout
+ * @returns {number[]}
+ */
+export declare function parseLsofPids(stdout: string): number[];
+/**
+ * `ss -H -lptn` satırlarından `pid=` değerlerini alır.
+ *
+ * @param {string} stdout
+ * @returns {number[]}
+ */
+export declare function parseSsPids(stdout: string): number[];
+/**
+ * Portu dinleyen yabancı süreçlerin PID listesi.
+ *
+ * @param {number} port
+ * @returns {Promise<number[]>}
+ */
+export declare function listListeningPids(port: number): Promise<number[]>;
+/**
+ * Porttaki dinleyicileri öldürür ve soketin boşalmasını kısa süre bekler.
+ *
+ * @param {number} port
+ * @returns {Promise<number[]>} öldürülen PID'ler
+ */
+export declare function murderPort(port: number): Promise<number[]>;
+/**
+ * Port doluysa ya net hata fırlatır ya da `--murder` ile temizler.
+ *
+ * Dinleyici listesi alınamazsa (araç yok / yetki) sessizce geçer; asıl bağlama
+ * `EADDRINUSE` ile yine düşer.
+ *
+ * @param {number} port
+ * @param {{ murder?: boolean }} [options]
+ * @returns {Promise<void>}
+ */
+export declare function ensurePortFree(port: number, options?: {
+    murder?: boolean;
+}): Promise<void>;