@certik/serverless-api 1.0.12 → 2.1.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 2.1.0
+
+- added exports field to package.json mapping subpaths to dist/ counterparts
+
+# 2.0.0
+
+- Migrate the whole repo to typescript
+
 # 1.0.12
 
 - fixed incorrect parsing of empty request body in startLocalApp

package/README.md

@@ -59,7 +59,6 @@ export default async function handler(event) {
 }
 ```
 
-
 **Local Development Workflow**
 
 ```bash

package/dist/deploy.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pulumi program entry point.
+ *
+ * Loads routes from the local `routes/` directory and deploys
+ * the full serverless API stack via {@link createPulumiAPIApp}.
+ */
+export default function main(): Promise<{
+    zipFileName: string;
+    zipFileHash: string;
+    routes: Record<string, {
+        method: string;
+        timeout: number;
+        url: string;
+    }>;
+    runtime: import("@pulumi/aws/lambda/index.js").Runtime;
+    hostedZone: string;
+    domainName: string;
+    readme: string;
+}>;
+//# sourceMappingURL=deploy.d.ts.map

package/dist/deploy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../src/deploy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,wBAA8B,IAAI;;;;;;;;;;;;GAOjC"}

package/dist/deploy.js

@@ -0,0 +1,17 @@
+/**
+ * Pulumi program entry point.
+ *
+ * Loads routes from the local `routes/` directory and deploys
+ * the full serverless API stack via {@link createPulumiAPIApp}.
+ */
+import pathModule from "node:path";
+import { createPulumiAPIApp } from "./lib/app.js";
+import { dirname } from "./lib/path.js";
+import { getRoutes } from "./lib/routes.js";
+export default async function main() {
+    return createPulumiAPIApp({
+        routes: await getRoutes(pathModule.join(dirname(import.meta.url), "routes")),
+        bundleDevDependencies: true,
+    });
+}
+//# sourceMappingURL=deploy.js.map

package/dist/dev.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-export of {@link startLocalApp} for consumer convenience.
+ *
+ * Consumers can `import { startLocalApp } from "@certik/serverless-api/dev"`
+ * without pulling in the full library.
+ */
+export { startLocalApp } from "./lib/dev.js";
+//# sourceMappingURL=dev.d.ts.map

package/dist/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../src/dev.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/dev.js

@@ -0,0 +1,8 @@
+/**
+ * Re-export of {@link startLocalApp} for consumer convenience.
+ *
+ * Consumers can `import { startLocalApp } from "@certik/serverless-api/dev"`
+ * without pulling in the full library.
+ */
+export { startLocalApp } from "./lib/dev.js";
+//# sourceMappingURL=dev.js.map

package/dist/entrypoint.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared Lambda entrypoint.
+ *
+ * All Lambda functions deployed by this library share this single
+ * entrypoint. It discovers routes once on cold start, then matches
+ * each incoming API Gateway event to the correct handler, applying
+ * timeout enforcement and CORS headers.
+ *
+ * @module entrypoint
+ */
+import type { LambdaEvent, LambdaContext, LambdaResponse } from "./lib/types.js";
+/**
+ * The Lambda handler invoked by API Gateway.
+ *
+ * On the first invocation (cold start), routes are loaded from the
+ * `routes/` directory and cached for subsequent warm invocations.
+ * The handler matches the request path and HTTP method to a route,
+ * applies the configured timeout, and injects CORS headers when
+ * the route defines a `corsOrigin`.
+ *
+ * @param event - The API Gateway proxy integration event.
+ * @param context - The Lambda execution context.
+ * @returns The HTTP response to send back through API Gateway.
+ */
+export declare const handler: (event: LambdaEvent, context: LambdaContext) => Promise<LambdaResponse>;
+//# sourceMappingURL=entrypoint.d.ts.map

package/dist/entrypoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoint.d.ts","sourceRoot":"","sources":["../src/entrypoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAEV,WAAW,EACX,aAAa,EACb,cAAc,EACf,MAAM,gBAAgB,CAAC;AAOxB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,OAAO,GAClB,OAAO,WAAW,EAClB,SAAS,aAAa,KACrB,OAAO,CAAC,cAAc,CAiExB,CAAC"}

package/dist/entrypoint.js

@@ -0,0 +1,78 @@
+/**
+ * Shared Lambda entrypoint.
+ *
+ * All Lambda functions deployed by this library share this single
+ * entrypoint. It discovers routes once on cold start, then matches
+ * each incoming API Gateway event to the correct handler, applying
+ * timeout enforcement and CORS headers.
+ *
+ * @module entrypoint
+ */
+import pathModule from "node:path";
+import { getRoutes } from "./lib/routes.js";
+/** Cached routes — resolved once on cold start. */
+let cachedRoutes = null;
+/**
+ * The Lambda handler invoked by API Gateway.
+ *
+ * On the first invocation (cold start), routes are loaded from the
+ * `routes/` directory and cached for subsequent warm invocations.
+ * The handler matches the request path and HTTP method to a route,
+ * applies the configured timeout, and injects CORS headers when
+ * the route defines a `corsOrigin`.
+ *
+ * @param event - The API Gateway proxy integration event.
+ * @param context - The Lambda execution context.
+ * @returns The HTTP response to send back through API Gateway.
+ */
+export const handler = async (event, context) => {
+    if (!cachedRoutes) {
+        cachedRoutes = await getRoutes(pathModule.resolve("routes"));
+    }
+    const currentRoute = cachedRoutes.find((route) => {
+        return (route.path === event.path &&
+            route.method.toLowerCase() === event.httpMethod.toLowerCase());
+    });
+    if (!currentRoute) {
+        return {
+            statusCode: 404,
+            body: "Not Found",
+        };
+    }
+    const extraHeaders = {};
+    if (currentRoute.corsOrigin) {
+        extraHeaders["Access-Control-Allow-Origin"] = currentRoute.corsOrigin;
+    }
+    let timeoutId;
+    const response = await Promise.race([
+        (async () => {
+            let body = event.body ? event.body : null;
+            if (event.isBase64Encoded && body) {
+                body = Buffer.from(body, "base64").toString("utf-8");
+            }
+            const rp = await currentRoute.handler({
+                ...event,
+                body,
+                isBase64Encoded: false,
+            }, context);
+            return rp;
+        })(),
+        new Promise(function timeoutResponse(resolve) {
+            timeoutId = setTimeout(() => {
+                resolve({
+                    statusCode: 408,
+                    body: `Request Timeout after ${currentRoute.timeout} seconds`,
+                });
+            }, currentRoute.timeout * 1000);
+        }),
+    ]);
+    clearTimeout(timeoutId);
+    return {
+        ...response,
+        headers: {
+            ...response.headers,
+            ...extraHeaders,
+        },
+    };
+};
+//# sourceMappingURL=entrypoint.js.map

package/dist/handler.d.ts

@@ -0,0 +1,2 @@
+export { handler } from "./entrypoint.js";
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC"}

package/{index.js → dist/handler.js}

@@ -1 +1,2 @@
 export { handler } from "./entrypoint.js";
+//# sourceMappingURL=handler.js.map

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Public API surface of `@certik/serverless-api`.
+ *
+ * Re-exports the key utilities consumers need to build and
+ * deploy their own serverless APIs.
+ *
+ * @packageDocumentation
+ */
+export { dirname } from "./lib/path.js";
+export { startLocalApp } from "./lib/dev.js";
+export { createPulumiAPIApp } from "./lib/app.js";
+export { getRoutes } from "./lib/routes.js";
+export type { Route, RouteHandler, RouteModule, LambdaEvent, LambdaContext, LambdaResponse, PulumiAPIAppOptions, LocalAppOptions, PackOptions, PackResult, } from "./lib/types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EACV,KAAK,EACL,YAAY,EACZ,WAAW,EACX,WAAW,EACX,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,WAAW,EACX,UAAU,GACX,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * Public API surface of `@certik/serverless-api`.
+ *
+ * Re-exports the key utilities consumers need to build and
+ * deploy their own serverless APIs.
+ *
+ * @packageDocumentation
+ */
+export { dirname } from "./lib/path.js";
+export { startLocalApp } from "./lib/dev.js";
+export { createPulumiAPIApp } from "./lib/app.js";
+export { getRoutes } from "./lib/routes.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/app.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Pulumi deployment logic for the serverless API.
+ *
+ * Creates the full AWS infrastructure stack: Lambda functions,
+ * API Gateway, custom domain, ACM certificate, and Route 53
+ * DNS records. Each route gets its own Lambda function, all
+ * sharing the same source zip and entrypoint.
+ *
+ * @module app
+ */
+import * as aws from "@pulumi/aws";
+import type { PulumiAPIAppOptions } from "./types.js";
+export { getWildcardCertificateName } from "./domain.js";
+/**
+ * Create and deploy the full Pulumi serverless API stack.
+ *
+ * This provisions:
+ * - An S3 bucket object containing the zipped source code.
+ * - One Lambda function per route.
+ * - An API Gateway REST API wiring routes to Lambdas.
+ * - A custom domain with ACM certificate and Route 53 alias record.
+ *
+ * @param options - Deployment options including routes and bundling flags.
+ * @returns Deployment metadata: zip info, route URLs, runtime, and README.
+ */
+export declare function createPulumiAPIApp({ routes, bundleDevDependencies, }: PulumiAPIAppOptions): Promise<{
+    zipFileName: string;
+    zipFileHash: string;
+    routes: Record<string, {
+        method: string;
+        timeout: number;
+        url: string;
+    }>;
+    runtime: aws.lambda.Runtime;
+    hostedZone: string;
+    domainName: string;
+    readme: string;
+}>;
+//# sourceMappingURL=app.d.ts.map

package/dist/lib/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/lib/app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AAKnC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAMtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEzD;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,MAAM,EACN,qBAA6B,GAC9B,EAAE,mBAAmB;;;;gBAkHc,MAAM;iBAAW,MAAM;aAAO,MAAM;;;;;;GAwBvE"}

package/dist/lib/app.js

@@ -0,0 +1,139 @@
+/**
+ * Pulumi deployment logic for the serverless API.
+ *
+ * Creates the full AWS infrastructure stack: Lambda functions,
+ * API Gateway, custom domain, ACM certificate, and Route 53
+ * DNS records. Each route gets its own Lambda function, all
+ * sharing the same source zip and entrypoint.
+ *
+ * @module app
+ */
+import * as aws from "@pulumi/aws";
+import * as apigateway from "@pulumi/aws-apigateway";
+import * as pulumi from "@pulumi/pulumi";
+import { readFile } from "node:fs/promises";
+import { getWildcardCertificateName } from "./domain.js";
+import { isReservedEnvName } from "./env.js";
+import { packAndZip } from "./pack.js";
+export { getWildcardCertificateName } from "./domain.js";
+/**
+ * Create and deploy the full Pulumi serverless API stack.
+ *
+ * This provisions:
+ * - An S3 bucket object containing the zipped source code.
+ * - One Lambda function per route.
+ * - An API Gateway REST API wiring routes to Lambdas.
+ * - A custom domain with ACM certificate and Route 53 alias record.
+ *
+ * @param options - Deployment options including routes and bundling flags.
+ * @returns Deployment metadata: zip info, route URLs, runtime, and README.
+ */
+export async function createPulumiAPIApp({ routes, bundleDevDependencies = false, }) {
+    const { zipFileName, zipFileHash } = await packAndZip({
+        bundleDevDependencies,
+    });
+    const projectName = pulumi.getProject();
+    const stackName = pulumi.getStack();
+    const namespace = `wf-${stackName}-${projectName}-${stackName}`;
+    const config = new pulumi.Config();
+    const sourceBucketName = config.require("sourceBucket");
+    const hostedZone = config.require("hostedZone");
+    const runtime = config.require("runtime");
+    let subdomain = config.get("subdomain");
+    if (!subdomain) {
+        subdomain = projectName.startsWith("api-")
+            ? projectName.slice(4)
+            : projectName;
+    }
+    const domainName = `${subdomain}.${hostedZone}`;
+    const wildcardCertificateName = getWildcardCertificateName(domainName);
+    const lambdaRoleName = config.get("lambdaRole");
+    const role = aws.iam.getRole({ name: lambdaRoleName });
+    const sourceBucket = aws.s3.getBucket({ bucket: sourceBucketName });
+    const sourceKey = `${namespace}/sourcecode.zip`;
+    const sourceS3File = new aws.s3.BucketObject(`${namespace}-s3-sourcecode`, {
+        bucket: sourceBucket.then((b) => b.id),
+        key: sourceKey,
+        source: new pulumi.asset.FileArchive(zipFileName),
+        sourceHash: zipFileHash,
+    });
+    const site = new apigateway.RestAPI(namespace, {
+        routes: routes.map(({ name, path, method, timeout, memorySize, environmentVariables }) => {
+            const variables = environmentVariables
+                ? environmentVariables.reduce((acc, envName) => {
+                    if (isReservedEnvName(envName)) {
+                        return acc;
+                    }
+                    if (process.env[envName]) {
+                        acc[envName] = process.env[envName];
+                    }
+                    else {
+                        console.warn(`Environment variable not set: process.env.${envName}`);
+                    }
+                    return acc;
+                }, {})
+                : {};
+            return {
+                path,
+                method: method,
+                eventHandler: new aws.lambda.Function(`${namespace}-${name}`.slice(0, 56), {
+                    name: `${namespace}-${name}`.slice(0, 56),
+                    role: role.then((r) => r.arn),
+                    runtime,
+                    s3Bucket: sourceBucketName,
+                    s3Key: sourceS3File.key,
+                    handler: "entrypoint.handler",
+                    sourceCodeHash: zipFileHash,
+                    timeout: timeout + 10,
+                    memorySize,
+                    environment: { variables },
+                }),
+            };
+        }),
+    });
+    const certificate = await aws.acm.getCertificate({
+        domain: wildcardCertificateName,
+        statuses: ["ISSUED"],
+    });
+    const zone = await aws.route53.getZone({ name: hostedZone }, { async: true });
+    const domain = new aws.apigateway.DomainName(namespace, {
+        certificateArn: certificate.arn,
+        domainName,
+    });
+    const _basePathMapping = new aws.apigateway.BasePathMapping(namespace, {
+        restApi: site.api,
+        stageName: site.stage.stageName,
+        domainName: domain.domainName,
+    });
+    const _dnsRecord = new aws.route53.Record(namespace, {
+        type: "A",
+        zoneId: zone.zoneId,
+        name: domainName,
+        aliases: [
+            {
+                name: domain.cloudfrontDomainName,
+                zoneId: domain.cloudfrontZoneId,
+                evaluateTargetHealth: false,
+            },
+        ],
+    });
+    const routesInfo = routes.reduce((acc, { name, method, timeout, path }) => {
+        acc[name] = {
+            method,
+            timeout,
+            url: `https://${domainName}${path}`,
+        };
+        return acc;
+    }, {});
+    const readme = (await readFile("./README.md")).toString();
+    return {
+        zipFileName,
+        zipFileHash,
+        routes: routesInfo,
+        runtime,
+        hostedZone,
+        domainName,
+        readme,
+    };
+}
+//# sourceMappingURL=app.js.map

package/dist/lib/const.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Default and maximum configuration constants for Lambda functions.
+ *
+ * @module const
+ */
+/** Default Lambda timeout in seconds. */
+export declare const DEFAULT_TIMEOUT = 30;
+/** Maximum allowed Lambda timeout in seconds. */
+export declare const MAX_TIMEOUT = 90;
+/** Default Lambda memory allocation in megabytes. */
+export declare const DEFAULT_MEMORY_SIZE = 128;
+//# sourceMappingURL=const.d.ts.map

package/dist/lib/const.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../../src/lib/const.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yCAAyC;AACzC,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,iDAAiD;AACjD,eAAO,MAAM,WAAW,KAAK,CAAC;AAE9B,qDAAqD;AACrD,eAAO,MAAM,mBAAmB,MAAM,CAAC"}

package/dist/lib/const.js

@@ -0,0 +1,12 @@
+/**
+ * Default and maximum configuration constants for Lambda functions.
+ *
+ * @module const
+ */
+/** Default Lambda timeout in seconds. */
+export const DEFAULT_TIMEOUT = 30;
+/** Maximum allowed Lambda timeout in seconds. */
+export const MAX_TIMEOUT = 90;
+/** Default Lambda memory allocation in megabytes. */
+export const DEFAULT_MEMORY_SIZE = 128;
+//# sourceMappingURL=const.js.map

package/dist/lib/cors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CORS preflight route generation.
+ *
+ * @module cors
+ */
+import type { Route } from "./types.js";
+/**
+ * Create an `OPTIONS` preflight route that responds with permissive
+ * CORS headers.
+ *
+ * The generated route allows all origins (`*`), all standard HTTP
+ * methods, and all request headers.
+ *
+ * @param name - A unique name for the preflight route.
+ * @param path - The URL path this preflight route handles.
+ * @returns A fully configured {@link Route} for the OPTIONS method.
+ */
+export declare function corsPreflight(name: string, path: string): Route;
+//# sourceMappingURL=cors.d.ts.map

package/dist/lib/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../src/lib/cors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAqB/D"}

package/dist/lib/cors.js

@@ -0,0 +1,38 @@
+/**
+ * CORS preflight route generation.
+ *
+ * @module cors
+ */
+/**
+ * Create an `OPTIONS` preflight route that responds with permissive
+ * CORS headers.
+ *
+ * The generated route allows all origins (`*`), all standard HTTP
+ * methods, and all request headers.
+ *
+ * @param name - A unique name for the preflight route.
+ * @param path - The URL path this preflight route handles.
+ * @returns A fully configured {@link Route} for the OPTIONS method.
+ */
+export function corsPreflight(name, path) {
+    return {
+        name,
+        path,
+        method: "OPTIONS",
+        timeout: 30,
+        memorySize: 128,
+        environmentVariables: [],
+        handler: async () => {
+            return {
+                body: "",
+                statusCode: 200,
+                headers: {
+                    "Access-Control-Allow-Origin": "*",
+                    "Access-Control-Allow-Methods": "GET, POST, OPTIONS, PUT, PATCH, DELETE",
+                    "Access-Control-Allow-Headers": "*",
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=cors.js.map

package/dist/lib/dev.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Local development server powered by Express.
+ *
+ * Translates incoming HTTP requests into the AWS API Gateway
+ * proxy event format so route handlers can run identically
+ * in local development and in Lambda.
+ *
+ * @module dev
+ */
+import { type Request } from "express";
+import type { LambdaEvent, LocalAppOptions } from "./types.js";
+/**
+ * Map an Express {@link Request} to an API Gateway
+ * {@link LambdaEvent} proxy integration event.
+ *
+ * The request body is base64-encoded when it is a `Buffer`
+ * (as produced by `express.raw()`), matching how API Gateway
+ * delivers binary payloads.
+ *
+ * @param req - The incoming Express request.
+ * @returns A synthetic Lambda event object.
+ */
+export declare function mapRequestToEvent(req: Request): LambdaEvent;
+/**
+ * Start a local Express server that serves the given routes using
+ * the shared Lambda handler.
+ *
+ * Each route is registered at both `/{path}` and `/dev/{path}`
+ * for backward compatibility with the serverless-offline convention.
+ * The server listens on the port specified by the `PORT` environment
+ * variable, defaulting to `4000`.
+ *
+ * @param options - The routes and handler to serve.
+ * @param options.routes - Resolved route definitions.
+ * @param options.handler - The shared Lambda entrypoint handler.
+ */
+export declare function startLocalApp({ routes, handler, }: LocalAppOptions): Promise<void>;
+//# sourceMappingURL=dev.d.ts.map

package/dist/lib/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/lib/dev.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAgB,EAAE,KAAK,OAAO,EAAiB,MAAM,SAAS,CAAC;AAE/D,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAgB3D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,EAClC,MAAM,EACN,OAAO,GACR,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCjC"}

package/dist/lib/dev.js

@@ -0,0 +1,78 @@
+/**
+ * Local development server powered by Express.
+ *
+ * Translates incoming HTTP requests into the AWS API Gateway
+ * proxy event format so route handlers can run identically
+ * in local development and in Lambda.
+ *
+ * @module dev
+ */
+import express from "express";
+/**
+ * Map an Express {@link Request} to an API Gateway
+ * {@link LambdaEvent} proxy integration event.
+ *
+ * The request body is base64-encoded when it is a `Buffer`
+ * (as produced by `express.raw()`), matching how API Gateway
+ * delivers binary payloads.
+ *
+ * @param req - The incoming Express request.
+ * @returns A synthetic Lambda event object.
+ */
+export function mapRequestToEvent(req) {
+    return {
+        resource: req.path,
+        path: req.path,
+        httpMethod: req.method,
+        requestContext: {
+            resourcePath: req.path,
+            httpMethod: req.method,
+            path: req.path,
+        },
+        headers: req.headers,
+        multiValueHeaders: {},
+        queryStringParameters: req.query,
+        body: Buffer.isBuffer(req.body) ? req.body.toString("base64") : "",
+        isBase64Encoded: true,
+    };
+}
+/**
+ * Start a local Express server that serves the given routes using
+ * the shared Lambda handler.
+ *
+ * Each route is registered at both `/{path}` and `/dev/{path}`
+ * for backward compatibility with the serverless-offline convention.
+ * The server listens on the port specified by the `PORT` environment
+ * variable, defaulting to `4000`.
+ *
+ * @param options - The routes and handler to serve.
+ * @param options.routes - Resolved route definitions.
+ * @param options.handler - The shared Lambda entrypoint handler.
+ */
+export async function startLocalApp({ routes, handler, }) {
+    const app = express();
+    app.use(express.raw({
+        inflate: true,
+        limit: "10mb",
+        type: () => true,
+    }));
+    const port = Number(process.env["PORT"] ?? 4000);
+    routes.forEach(({ path, method }) => {
+        const m = method || "GET";
+        console.log(`registering ${m} ${path}`);
+        const callback = async (req, res) => {
+            const context = {};
+            const result = await handler(mapRequestToEvent(req), context);
+            for (const [key, value] of Object.entries(result.headers ?? {})) {
+                res.set(key, value);
+            }
+            res.status(result.statusCode);
+            res.send(result.body);
+        };
+        app[m.toLowerCase()](path, callback);
+        app[m.toLowerCase()](`/dev${path}`, callback);
+    });
+    console.log(`listening on http://localhost:${port}`);
+    app.listen(port);
+}
+//# sourceMappingURL=dev.js.map

package/dist/lib/domain.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Domain name utilities.
+ *
+ * @module domain
+ */
+/**
+ * Derive a wildcard certificate name from a fully-qualified domain.
+ *
+ * Replaces the leftmost label with `*` so the result matches an
+ * ACM wildcard certificate (e.g. `data.example.com` → `*.example.com`).
+ *
+ * @param domainName - The fully-qualified domain name.
+ * @returns The wildcard domain (e.g. `*.example.com`).
+ */
+export declare function getWildcardCertificateName(domainName: string): string;
+//# sourceMappingURL=domain.d.ts.map

package/dist/lib/domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../../src/lib/domain.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGrE"}