boltdocs 2.8.3 → 2.9.0

package/dist/node/index.d.cts

@@ -1,6 +1,9 @@
 
 import { InlineConfig, Plugin } from "vite";
 import { EXIT, SKIP } from "unist-util-visit";
+import { VercelRequest, VercelResponse } from "@vercel/node";
+import { HandlerEvent, HandlerResponse } from "@netlify/functions";
+import { Writable } from "node:stream";
 //#region src/shared/types.d.ts
 /**
  * Represents a single social link in the configuration.
@@ -193,15 +196,47 @@ interface BoltdocsAlgoliaConfig {
   apiKey: string;
   indexName: string;
 }
+/**
+ * Configuration for Giscus comments.
+ */
+interface BoltdocsGiscusConfig {
+  repo: string;
+  repoId: string;
+  category?: string;
+  categoryId?: string;
+  mapping?: 'pathname' | 'url' | 'title' | 'og:title' | 'specific' | 'number';
+  strict?: '0' | '1' | boolean;
+  reactionsEnabled?: '0' | '1' | boolean;
+  emitMetadata?: '0' | '1' | boolean;
+  inputPosition?: 'top' | 'bottom';
+  theme?: string;
+  darkTheme?: string;
+  lang?: string;
+  loading?: 'lazy' | 'eager';
+}
+/**
+ * Configuration for custom feedback system using GitHub Discussions API.
+ */
+interface BoltdocsCustomFeedbackConfig {
+  enabled: boolean;
+  owner: string;
+  repo: string;
+  categorySlug?: string;
+  endpoint?: string;
+}
 interface BoltdocsIntegrationsConfig {
   ga4?: BoltdocsGA4Config;
   gtm?: BoltdocsGTMConfig;
   algolia?: BoltdocsAlgoliaConfig;
+  feedback?: {
+    giscus?: BoltdocsGiscusConfig;
+    custom?: BoltdocsCustomFeedbackConfig;
+  };
 }
 /**
  * The root configuration object for Boltdocs.
  */
-interface BoltdocsConfig {
+interface BoltdocsConfig$1 {
   siteUrl?: string;
   docsDir?: string;
   base?: string;
@@ -214,9 +249,8 @@ interface BoltdocsConfig {
   security?: BoltdocsSecurityConfig;
   seo?: BoltdocsSeoConfig;
   integrations?: BoltdocsIntegrationsConfig;
-  /** Aggregated metadata from local meta.json files */
-  directoryMeta?: Record<string, any>;
-  vite?: any;
+  directoryMeta?: Record<string, unknown>;
+  vite?: unknown;
 }
 /**
  * Global namespace for Boltdocs types that can be augmented by generated code.
@@ -248,7 +282,7 @@ type BoltdocsRoutePathWithFallback = BoltdocsRoutePath extends never ? string :
  *
  * @param config - The Boltdocs configuration object
  */
-declare function defineConfig(config: BoltdocsConfig): BoltdocsConfig;
+declare function defineConfig(config: BoltdocsConfig$1): BoltdocsConfig$1;
 //#endregion
 //#region src/node/config.d.ts
 /**
@@ -259,7 +293,7 @@ declare function defineConfig(config: BoltdocsConfig): BoltdocsConfig;
  * @param root - The project root directory (defaults to process.cwd())
  * @returns The merged configuration object
  */
-declare function resolveConfig(docsDir: string, root?: string): Promise<BoltdocsConfig>;
+declare function resolveConfig(docsDir: string, root?: string): Promise<BoltdocsConfig$1>;
 //#endregion
 //#region src/node/plugin/types.d.ts
 /**
@@ -279,7 +313,7 @@ interface BoltdocsPluginOptions {
  * @param config - The resolved Boltdocs configuration containing custom plugins and components
  * @returns A string of JavaScript code to be evaluated by the browser
  */
-declare function generateEntryCode(options: BoltdocsPluginOptions, config?: BoltdocsConfig): string;
+declare function generateEntryCode(options: BoltdocsPluginOptions, config?: BoltdocsConfig$1): string;
 //#endregion
 //#region src/node/routes/types.d.ts
 /**
@@ -363,27 +397,29 @@ interface RouteMeta {
   slugParts?: string[];
 }
 //#endregion
-//#region src/node/utils.d.ts
+//#region src/node/cache.d.ts
 /**
- * Normalizes a file path by replacing Windows backslashes with forward slashes.
- * Ensures consistent path handling across different operating systems.
- *
- * @param p - The file path to normalize
- * @returns The normalized path using forward slashes
+ * Specialized cache for processed assets (e.g., optimized images).
  */
-declare function normalizePath(p: string): string;
+declare class AssetCache {
+  private readonly assetsDir;
+  private hashMap;
+  constructor(root?: string);
+  getFileHash(filePath: string): Promise<string>;
+  get(sourcePath: string, cacheKey: string): Promise<string | null>;
+  set(sourcePath: string, cacheKey: string, content: Buffer | string, sourceHash: string): void;
+  private getCachedPath;
+  clear(): void;
+  flush(): Promise<void>;
+}
 /**
- * Sanitizes a filename or path component by removing dangerous characters.
- * Prevents multiple dots to avoid path traversal tricks.
- *
- * @param name - The name to sanitize
- * @returns The sanitized name
+ * Flushes all pending background cache operations.
  */
-declare function sanitizeFilename(name: string): string;
+declare function flushCache(): Promise<void>;
 //#endregion
 //#region src/node/plugins/plugin-types.d.ts
 interface PluginContext {
-  readonly config: BoltdocsConfig;
+  readonly config: BoltdocsConfig$1;
   readonly logger: PluginLogger;
   readonly store: PluginStore;
   readonly meta: PluginMeta;
@@ -412,6 +448,14 @@ interface PluginLifecycleHooks {
   beforeDev?: (ctx: PluginContext) => Promise<void> | void;
   afterDev?: (ctx: PluginContext) => Promise<void> | void;
   buildEnd?: (ctx: PluginContext) => Promise<void> | void;
+  transformSource?: (ctx: PluginContext, params: {
+    code: string;
+    filePath: string;
+  }) => Promise<{
+    code: string;
+  }> | {
+    code: string;
+  };
   transformMdx?: (ctx: PluginContext, params: {
     code: string;
     filePath: string;
@@ -493,7 +537,7 @@ declare class PluginLifecycleManager {
   private store;
   private docsDir;
   private rootDir;
-  constructor(plugins: SecureBoltdocsPlugin[], config: BoltdocsConfig, docsDir?: string, rootDir?: string);
+  constructor(plugins: SecureBoltdocsPlugin[], config: BoltdocsConfig$1, docsDir?: string, rootDir?: string);
   runHook(hookName: keyof PluginLifecycleHooks, ...args: unknown[]): Promise<void>;
   runChain<TParams>(hookName: keyof PluginLifecycleHooks, initialParams: TParams): Promise<TParams>;
   private getSortedPlugins;
@@ -685,12 +729,312 @@ declare const MDX_NODES: {
 //#region src/node/plugins/index.d.ts
 declare function createPlugin(plugin: SecureBoltdocsPlugin): SecureBoltdocsPlugin;
 //#endregion
+//#region src/node/feedback/adapters/vercel.d.ts
+declare function handleVercelFeedback(req: VercelRequest, res: VercelResponse): Promise<VercelResponse | undefined>;
+//#endregion
+//#region src/node/feedback/adapters/netlify.d.ts
+declare function handleNetlifyFeedback(event: HandlerEvent, env?: Record<string, string | undefined>): Promise<HandlerResponse>;
+//#endregion
+//#region src/node/feedback/adapters/web.d.ts
+declare function handleWebFeedback(request: Request, env?: Record<string, string | undefined>): Promise<Response>;
+//#endregion
+//#region ../../node_modules/.pnpm/@types+aws-lambda@8.10.161/node_modules/@types/aws-lambda/common/api-gateway.d.ts
+// Default authorizer type, prefer using a specific type with the "...WithAuthorizer..." variant types.
+// Note that this doesn't have to be a context from a custom lambda outhorizer, AWS also has a cognito
+// authorizer type and could add more, so the property won't always be a string.
+type APIGatewayEventDefaultAuthorizerContext = undefined | null | {
+  [name: string]: any;
+};
+// The requestContext property of both request authorizer and proxy integration events.
+interface APIGatewayEventRequestContextWithAuthorizer<TAuthorizerContext> {
+  accountId: string;
+  apiId: string; // This one is a bit confusing: it is not actually present in authorizer calls
+  // and proxy calls without an authorizer. We model this by allowing undefined in the type,
+  // since it ends up the same and avoids breaking users that are testing the property.
+  // This lets us allow parameterizing the authorizer for proxy events that know what authorizer
+  // context values they have.
+  authorizer: TAuthorizerContext;
+  connectedAt?: number | undefined;
+  connectionId?: string | undefined;
+  domainName?: string | undefined;
+  domainPrefix?: string | undefined;
+  eventType?: string | undefined;
+  extendedRequestId?: string | undefined;
+  protocol: string;
+  httpMethod: string;
+  identity: APIGatewayEventIdentity;
+  messageDirection?: string | undefined;
+  messageId?: string | null | undefined;
+  path: string;
+  stage: string;
+  requestId: string;
+  requestTime?: string | undefined;
+  requestTimeEpoch: number;
+  resourceId: string;
+  resourcePath: string;
+  routeKey?: string | undefined;
+}
+interface APIGatewayEventClientCertificate {
+  clientCertPem: string;
+  serialNumber: string;
+  subjectDN: string;
+  issuerDN: string;
+  validity: {
+    notAfter: string;
+    notBefore: string;
+  };
+}
+interface APIGatewayEventIdentity {
+  accessKey: string | null;
+  accountId: string | null;
+  apiKey: string | null;
+  apiKeyId: string | null;
+  caller: string | null;
+  clientCert: APIGatewayEventClientCertificate | null;
+  cognitoAuthenticationProvider: string | null;
+  cognitoAuthenticationType: string | null;
+  cognitoIdentityId: string | null;
+  cognitoIdentityPoolId: string | null;
+  principalOrgId: string | null;
+  sourceIp: string;
+  user: string | null;
+  userAgent: string | null;
+  userArn: string | null;
+  vpcId?: string | undefined;
+  vpceId?: string | undefined;
+}
+//#endregion
+//#region ../../node_modules/.pnpm/@types+aws-lambda@8.10.161/node_modules/@types/aws-lambda/handler.d.ts
+/**
+ * {@link Handler} context parameter.
+ * See {@link https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-context.html AWS documentation}.
+ */
+interface Context {
+  callbackWaitsForEmptyEventLoop: boolean;
+  functionName: string;
+  functionVersion: string;
+  invokedFunctionArn: string;
+  memoryLimitInMB: string;
+  awsRequestId: string;
+  logGroupName: string;
+  logStreamName: string;
+  identity?: CognitoIdentity | undefined;
+  clientContext?: ClientContext | undefined;
+  tenantId?: string | undefined;
+  getRemainingTimeInMillis(): number; // Functions for compatibility with earlier Node.js Runtime v0.10.42
+  // No longer documented, so they are deprecated, but they still work
+  // as of the 12.x runtime, so they are not removed from the types.
+  /** @deprecated Use handler callback or promise result */
+  done(error?: Error, result?: any): void;
+  /** @deprecated Use handler callback with first argument or reject a promise result */
+  fail(error: Error | string): void;
+  /** @deprecated Use handler callback with second argument or resolve a promise result */
+  succeed(messageOrObject: any): void; // Unclear what behavior this is supposed to have, I couldn't find any still extant reference,
+  // and it behaves like the above, ignoring the object parameter.
+  /** @deprecated Use handler callback or promise result */
+  succeed(message: string, object: any): void;
+}
+interface CognitoIdentity {
+  cognitoIdentityId: string;
+  cognitoIdentityPoolId: string;
+}
+interface ClientContext {
+  client: ClientContextClient;
+  custom?: any;
+  env: ClientContextEnv;
+}
+interface ClientContextClient {
+  installationId: string;
+  appTitle: string;
+  appVersionName: string;
+  appVersionCode: string;
+  appPackageName: string;
+}
+interface ClientContextEnv {
+  platformVersion: string;
+  platform: string;
+  make: string;
+  model: string;
+  locale: string;
+}
+/**
+ * Interface for using response streaming from AWS Lambda.
+ * To indicate to the runtime that Lambda should stream your function’s responses, you must wrap your function handler with the `awslambda.streamifyResponse()` decorator.
+ *
+ * The `streamifyResponse` decorator accepts the following additional parameter, `responseStream`, besides the default node handler parameters, `event`, and `context`.
+ * The new `responseStream` object provides a stream object that your function can write data to. Data written to this stream is sent immediately to the client. You can optionally set the Content-Type header of the response to pass additional metadata to your client about the contents of the stream.
+ *
+ * {@link https://aws.amazon.com/blogs/compute/introducing-aws-lambda-response-streaming/ AWS blog post}
+ * {@link https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html AWS documentation}
+ *
+ * @example <caption>Writing to the response stream</caption>
+ * import 'aws-lambda';
+ *
+ * export const handler = awslambda.streamifyResponse(
+ *   async (event, responseStream, context) => {
+ *       responseStream.setContentType("text/plain");
+ *       responseStream.write("Hello, world!");
+ *       responseStream.end();
+ *   }
+ * );
+ *
+ * @example <caption>Using pipeline</caption>
+ * import 'aws-lambda';
+ * import { Readable } from 'stream';
+ * import { pipeline } from 'stream/promises';
+ * import zlib from 'zlib';
+ *
+ * export const handler = awslambda.streamifyResponse(
+ *   async (event, responseStream, context) => {
+ *     // As an example, convert event to a readable stream.
+ *     const requestStream = Readable.from(Buffer.from(JSON.stringify(event)));
+ *
+ *     await pipeline(requestStream, zlib.createGzip(), responseStream);
+ *   }
+ * );
+ */
+type StreamifyHandler<TEvent = any, TResult = any> = (event: TEvent, responseStream: awslambda.HttpResponseStream, context: Context) => TResult | Promise<TResult>;
+declare global {
+  namespace awslambda {
+    class HttpResponseStream extends Writable {
+      static from(writable: Writable, metadata: Record<string, unknown>): HttpResponseStream;
+      setContentType: (contentType: string) => void;
+    }
+    /**
+     * Decorator for using response streaming from AWS Lambda.
+     * To indicate to the runtime that Lambda should stream your function’s responses, you must wrap your function handler with the `awslambda.streamifyResponse()` decorator.
+     *
+     * The `streamifyResponse` decorator accepts the following additional parameter, `responseStream`, besides the default node handler parameters, `event`, and `context`.
+     * The new `responseStream` object provides a stream object that your function can write data to. Data written to this stream is sent immediately to the client. You can optionally set the Content-Type header of the response to pass additional metadata to your client about the contents of the stream.
+     *
+     * {@link https://aws.amazon.com/blogs/compute/introducing-aws-lambda-response-streaming/ AWS blog post}
+     * {@link https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html AWS documentation}
+     *
+     * @example <caption>Writing to the response stream</caption>
+     * import 'aws-lambda';
+     *
+     * export const handler = awslambda.streamifyResponse(
+     *   async (event, responseStream, context) => {
+     *       responseStream.setContentType("text/plain");
+     *       responseStream.write("Hello, world!");
+     *       responseStream.end();
+     *   }
+     * );
+     *
+     * @example <caption>Using pipeline</caption>
+     * import 'aws-lambda';
+     * import { Readable } from 'stream';
+     * import { pipeline } from 'stream/promises';
+     * import zlib from 'zlib';
+     *
+     * export const handler = awslambda.streamifyResponse(
+     *   async (event, responseStream, context) => {
+     *     // As an example, convert event to a readable stream.
+     *     const requestStream = Readable.from(Buffer.from(JSON.stringify(event)));
+     *
+     *     await pipeline(requestStream, zlib.createGzip(), responseStream);
+     *   }
+     * );
+     */
+    function streamifyResponse<TEvent = any, TResult = void>(handler: StreamifyHandler<TEvent, TResult>): StreamifyHandler<TEvent, TResult>;
+  }
+}
+//#endregion
+//#region ../../node_modules/.pnpm/@types+aws-lambda@8.10.161/node_modules/@types/aws-lambda/trigger/api-gateway-proxy.d.ts
+/**
+ * Works with Lambda Proxy Integration for Rest API or HTTP API integration Payload Format version 1.0
+ * @see - https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html
+ */
+type APIGatewayProxyEvent = APIGatewayProxyEventBase<APIGatewayEventDefaultAuthorizerContext>;
+interface APIGatewayProxyEventHeaders {
+  [name: string]: string | undefined;
+}
+interface APIGatewayProxyEventMultiValueHeaders {
+  [name: string]: string[] | undefined;
+}
+interface APIGatewayProxyEventPathParameters {
+  [name: string]: string | undefined;
+}
+interface APIGatewayProxyEventQueryStringParameters {
+  [name: string]: string | undefined;
+}
+interface APIGatewayProxyEventMultiValueQueryStringParameters {
+  [name: string]: string[] | undefined;
+}
+interface APIGatewayProxyEventStageVariables {
+  [name: string]: string | undefined;
+}
+interface APIGatewayProxyEventBase<TAuthorizerContext> {
+  body: string | null;
+  headers: APIGatewayProxyEventHeaders;
+  multiValueHeaders: APIGatewayProxyEventMultiValueHeaders;
+  httpMethod: string;
+  isBase64Encoded: boolean;
+  path: string;
+  pathParameters: APIGatewayProxyEventPathParameters | null;
+  queryStringParameters: APIGatewayProxyEventQueryStringParameters | null;
+  multiValueQueryStringParameters: APIGatewayProxyEventMultiValueQueryStringParameters | null;
+  stageVariables: APIGatewayProxyEventStageVariables | null;
+  requestContext: APIGatewayEventRequestContextWithAuthorizer<TAuthorizerContext>;
+  resource: string;
+}
+/**
+ * Works with Lambda Proxy Integration for Rest API or HTTP API integration Payload Format version 1.0
+ * @see - https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html
+ */
+interface APIGatewayProxyResult {
+  statusCode: number;
+  headers?: {
+    [header: string]: boolean | number | string;
+  } | undefined;
+  multiValueHeaders?: {
+    [header: string]: Array<boolean | number | string>;
+  } | undefined;
+  body: string;
+  isBase64Encoded?: boolean | undefined;
+}
+//#endregion
+//#region src/node/feedback/adapters/aws.d.ts
+declare function handleAwsFeedback(event: APIGatewayProxyEvent, env?: Record<string, string | undefined>): Promise<APIGatewayProxyResult>;
+//#endregion
+//#region src/node/feedback/handler.d.ts
+interface FeedbackHandlerOptions {
+  owner?: string;
+  repo?: string;
+  categorySlug?: string;
+  token?: string;
+  appId?: string;
+  privateKey?: string;
+  installationId?: string;
+}
+declare function handleFeedback(payload: unknown, env?: Record<string, string | undefined>, options?: FeedbackHandlerOptions): Promise<{
+  success: boolean;
+}>;
+//#endregion
+//#region src/node/utils.d.ts
+/**
+ * Normalizes a file path by replacing Windows backslashes with forward slashes.
+ * Ensures consistent path handling across different operating systems.
+ *
+ * @param p - The file path to normalize
+ * @returns The normalized path using forward slashes
+ */
+declare function normalizePath(p: string): string;
+/**
+ * Sanitizes a filename or path component by removing dangerous characters.
+ * Prevents multiple dots to avoid path traversal tricks.
+ *
+ * @param name - The name to sanitize
+ * @returns The sanitized name
+ */
+declare function sanitizeFilename(name: string): string;
+//#endregion
 //#region src/node/index.d.ts
 declare function boltdocs(options?: BoltdocsPluginOptions): Promise<Plugin[]>;
 /**
  * Generates the complete Vite configuration for a Boltdocs project.
  * This is used by the Boltdocs CLI to run Vite without a user-defined vite.config.ts.
  */
-declare function createViteConfig(root: string, mode?: 'development' | 'production'): Promise<InlineConfig>;
+declare function createViteConfig(root: string, mode?: 'development' | 'production', preResolvedConfig?: BoltdocsConfig): Promise<InlineConfig>;
 //#endregion
-export { type BoltdocsConfig, type BoltdocsPlugin, type BoltdocsPluginOptions, BoltdocsPluginStore, type BoltdocsThemeConfig, EXIT, MDX_NODES, NodeWithHProperties, PluginCompatibilityError, PluginContext, PluginError, PluginHookError, PluginLifecycleHooks, PluginLifecycleManager, PluginLogger, PluginMeta, PluginStore, PluginValidationError, type RouteMeta, SKIP, SecureBoltdocsPlugin, addNodeClass, createMdxAttribute, createMdxElement, createPlugin, createRehypeElement, createViteConfig, boltdocs as default, defineConfig, generateEntryCode, getNodeProperty, hasNodeClass, normalizePath, parseMetaString, removeNodeClass, resolveConfig, sanitizeFilename, setNodeProperty, validatePlugins, visitMdxElements, visitNodes, visitRehypeElements, visitRemarkHeadings, visitRemarkLinks };
+export { AssetCache, type BoltdocsConfig$1 as BoltdocsConfig, type BoltdocsPlugin, type BoltdocsPluginOptions, BoltdocsPluginStore, type BoltdocsThemeConfig, EXIT, MDX_NODES, NodeWithHProperties, PluginCompatibilityError, PluginContext, PluginError, PluginHookError, PluginLifecycleHooks, PluginLifecycleManager, PluginLogger, PluginMeta, PluginStore, PluginValidationError, type RouteMeta, SKIP, SecureBoltdocsPlugin, addNodeClass, createMdxAttribute, createMdxElement, createPlugin, createRehypeElement, createViteConfig, boltdocs as default, defineConfig, flushCache, generateEntryCode, getNodeProperty, handleAwsFeedback, handleFeedback, handleNetlifyFeedback, handleVercelFeedback, handleWebFeedback, hasNodeClass, normalizePath, parseMetaString, removeNodeClass, resolveConfig, sanitizeFilename, setNodeProperty, validatePlugins, visitMdxElements, visitNodes, visitRehypeElements, visitRemarkHeadings, visitRemarkLinks };