@karmaniverous/smoz 0.2.9 → 0.2.11

package/LICENSE

@@ -1,28 +1,28 @@
-BSD 3-Clause License
-
-Copyright (c) 2025, Jason Williscroft
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-3. Neither the name of the copyright holder nor the names of its
-   contributors may be used to endorse or promote products derived from
-   this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+BSD 3-Clause License
+
+Copyright (c) 2025, Jason Williscroft
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,81 +1,82 @@
-<div align="center">
-
-# SMOZ
-
-[Serverless](https://www.serverless.com/) · [Middy](https://middy.js.org/) · [OpenAPI 3.1](https://spec.openapis.org/oas/latest.html) · [Zod](https://zod.dev/)
-
-[![npm version](https://img.shields.io/npm/v/@karmaniverous/smoz.svg)](https://www.npmjs.com/package/@karmaniverous/smoz)
-![Node Current](https://img.shields.io/node/v/@karmaniverous/smoz)
-[![docs](https://img.shields.io/badge/docs-website-blue)](https://docs.karmanivero.us/smoz)
-[![changelog](https://img.shields.io/badge/changelog-latest-blue.svg)](https://github.com/karmaniverous/smoz/tree/main/CHANGELOG.md)
-[![license](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/karmaniverous/smoz/tree/main/LICENSE.md)
-
-</div>
-
-SMOZ is a small, pragmatic toolkit for authoring AWS Lambda handlers with [Middy] and [Zod], then aggregating Serverless functions and hand‑crafted OpenAPI 3.1 paths from a single, schema‑first application definition.
-
-- Keep prod code testable and framework‑agnostic
-- HTTP middleware with validation, shaping, errors, CORS, negotiation, and HEAD
-- Non‑HTTP flows stay lean (no middleware overhead)
-
-## Quick start (from zero)
-
-From an empty directory:
-
-```bash
-npx @karmaniverous/smoz init -i
-npx smoz dev -p 3000
-```
-
-- The first command scaffolds a new app and installs dependencies (including a local `smoz` bin).
-- The second command starts the inline local backend and keeps registers + OpenAPI fresh.
-- Open http://localhost:3000/openapi in your browser.
-
-Prefer `serverless‑offline`?
-
-```bash
-npx smoz dev -l offline -p 3000
-```
-
-Add your first endpoint (avoid clashing with the template’s hello):
-
-```bash
-npx smoz add rest/foo/get
-```
-
-## Quick links
-
-- [Overview](https://docs.karmanivero.us/smoz/documents/Overview.html)
-- [Why smoz?](https://docs.karmanivero.us/smoz/documents/Why_smoz_.html)
-- [Getting started](https://docs.karmanivero.us/smoz/documents/Getting_started.html)
-- [10-minute tour](https://docs.karmanivero.us/smoz/documents/10%E2%80%91minute_tour.html)
-- [HTTP Middleware](https://docs.karmanivero.us/smoz/documents/HTTP_middleware.html)
-- [Recipes](https://docs.karmanivero.us/smoz/documents/Recipes.html)
-  - [SQS function](https://docs.karmanivero.us/smoz/documents/Recipes.SQS_function.html)
-  - [Contexts + Cognito authorizer](https://docs.karmanivero.us/smoz/documents/Recipes.Contexts_+_Cognito_authorizer.html) - [Custom middleware insertion](https://docs.karmanivero.us/smoz/documents/Recipes.Custom_middleware_insertion.html)
-  - [Per‑function env](<https://docs.karmanivero.us/smoz/documents/Recipes.Per%E2%80%91function_env_(fnEnvKeys).html>)
-  - [Observability](<https://docs.karmanivero.us/smoz/documents/Recipes.Observability_(requestId_header).html>)
-  - [Troubleshooting](https://docs.karmanivero.us/smoz/documents/Recipes.Troubleshooting.html)
-- [Templates](https://docs.karmanivero.us/smoz/documents/Templates.html)
-- [CLI](https://docs.karmanivero.us/smoz/documents/CLI.html)
-- [Contributing](https://docs.karmanivero.us/smoz/documents/Contributing.html)
-
-## Install
-
-```bash
-npm i @karmaniverous/smoz zod zod-openapi
-```
-
-## Dev tooling (recommended):
-
-```bash
-npm i -D typescript typescript-eslint eslint prettier typedoc
-```
-
-## Docs and reference
-
-- [Docs site](https://docs.karmanivero.us/smoz)
-- [Changelog](https://github.com/karmaniverous/smoz/tree/main/CHANGELOG.md)
-- [License](https://github.com/karmaniverous/smoz/tree/main/LICENSE.md)
-- [Middy](https://middy.js.org/)
-- [Zod](https://zod.dev/)
+<div align="center">
+
+# SMOZ
+
+[Serverless](https://www.serverless.com/) · [Middy](https://middy.js.org/) · [OpenAPI 3.1](https://spec.openapis.org/oas/latest.html) · [Zod](https://zod.dev/)
+
+[![npm version](https://img.shields.io/npm/v/@karmaniverous/smoz.svg)](https://www.npmjs.com/package/@karmaniverous/smoz)
+![Node Current](https://img.shields.io/node/v/@karmaniverous/smoz)
+[![docs](https://img.shields.io/badge/docs-website-blue)](https://docs.karmanivero.us/smoz)
+[![changelog](https://img.shields.io/badge/changelog-latest-blue.svg)](https://github.com/karmaniverous/smoz/tree/main/CHANGELOG.md)
+[![license](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/karmaniverous/smoz/tree/main/LICENSE.md)
+
+</div>
+
+SMOZ is a small, pragmatic toolkit for authoring AWS Lambda handlers with [Middy] and [Zod], then aggregating Serverless functions and hand‑crafted OpenAPI 3.1 paths from a single, schema‑first application definition.
+
+- Keep prod code testable and framework‑agnostic
+- HTTP middleware with validation, shaping, errors, CORS, negotiation, and HEAD
+- Non‑HTTP flows stay lean (no middleware overhead)
+
+## Quick start (from zero)
+
+From an empty directory:
+
+```bash
+npx @karmaniverous/smoz init -i
+npx smoz dev -p 3000
+```
+
+- The first command scaffolds a new app and installs dependencies (including a local `smoz` bin).
+- The second command starts the inline local backend and keeps registers + OpenAPI fresh.
+- Open http://localhost:3000/openapi in your browser.
+
+Prefer `serverless‑offline`?
+
+```bash
+npx smoz dev -l offline -p 3000
+```
+
+Add your first endpoint (avoid clashing with the template’s hello):
+
+```bash
+npx smoz add rest/foo/get
+```
+
+## Quick links
+
+- [Overview](./docs-src/overview.md)
+- [Why smoz?](./docs-src/why-smoz.md)
+- [Getting started](./docs-src/getting-started.md)
+- [10-minute tour](./docs-src/tour-10-minutes.md)
+- [HTTP Middleware](https://docs.karmanivero.us/smoz/documents/HTTP_middleware.html)
+- [Recipes](./docs-src/recipes/index.md)
+  - [SQS function](./docs-src/recipes/sqs.md)
+  - [Step Functions function](./docs-src/recipes/step.md)
+  - [Contexts + Cognito authorizer](./docs-src/recipes/contexts-auth.md) - [Custom middleware insertion](./docs-src/recipes/custom-middleware.md)
+  - [Per‑function env](./docs-src/recipes/per-function-env.md)
+  - [Observability](./docs-src/recipes/observability.md)
+  - [Troubleshooting](./docs-src/recipes/troubleshooting.md)
+- [Templates](./docs-src/templates.md)
+- [CLI](./docs-src/cli.md)
+- [Contributing](./CONTRIBUTING.md)
+
+## Install
+
+```bash
+npm i @karmaniverous/smoz zod zod-openapi
+```
+
+## Dev tooling (recommended):
+
+```bash
+npm i -D typescript typescript-eslint eslint prettier typedoc
+```
+
+## Docs and reference
+
+- [Docs site](https://docs.karmanivero.us/smoz)
+- [Changelog](./CHANGELOG.md)
+- [License](LICENSE)
+- [Middy](https://middy.js.org/)
+- [Zod](https://zod.dev/)

package/dist/cjs/index.js

@@ -30,12 +30,23 @@ const baseEventTypeMapSchema = zod.z.object({
     firehose: zod.z.custom(),
     // eslint-disable-next-line @typescript-eslint/no-deprecated -- Upstream AWS types mark this as deprecated; we retain the token for compatibility with existing apps.
     'cognito-userpool': zod.z.custom(),
+    /**
+     * Step Functions → Lambda (Service Integration: Lambda Invoke)
+     *
+     * When Step Functions invokes Lambda via the AWS SDK integration
+     * (e.g., "arn:aws:states:::lambda:invoke"), the event received by the
+     * Lambda handler is an object that wraps the original input under a
+     * "Payload" key. The Payload is already parsed JSON.
+     *
+     * Notes:
+     * - We accept additional keys (e.g., StatusCode/ExecutedVersion in some
+     *   patterns) via passthrough.
+     * - For the common “request/response” integration where Step Functions
+     *   passes state directly, apps can still treat the event via their
+     *   own app-local event map if needed.
+     */
+    step: zod.z.object({ Payload: zod.z.unknown().optional() }).catchall(zod.z.unknown()),
 });
-// Notes:
-// - This list intentionally includes widely used, generic AWS events.
-// - Apps can extend the schema with custom or specialized tokens:
-//     const EventMap = baseEventTypeMapSchema.extend({ step: z.custom<MyStepEvent>() })
-// - Only tokens listed in your App's httpEventTypeTokens are treated as HTTP by the runtime.
 
 /**
  * Stage artifacts factory.
@@ -1043,10 +1054,10 @@ const buildAllServerlessFunctions = (registry, serverless, buildFnEnv) => {
 /**
  * App (schema‑first)
  *
+ * Overloads on create() preserve strong inference when eventTypeMapSchema is omitted.
  * Central orchestrator for a SMOZ application. You provide:
  * - Global/stage parameter schemas and env exposure keys
- * - Serverless defaults (handler filename/export and context map)
- * - Event‑type map schema (extendable: e.g., add 'step')
+ * - Serverless defaults (handler filename/export and context map) * - Event‑type map schema (extendable: e.g., add 'step')
  *
  * The instance:
  * - Validates configuration
@@ -1130,6 +1141,7 @@ const buildAllServerlessFunctions = (registry, serverless, buildFnEnv) => {
      * @param init - initialization object (schemas, serverless defaults, params/envKeys)
      * @returns a new App instance
      */
+    // Implementation (must come after overload signatures)
     static create(init) {
         return new App(init);
     }
@@ -1137,9 +1149,7 @@ const buildAllServerlessFunctions = (registry, serverless, buildFnEnv) => {
      * Register a function (HTTP or non‑HTTP).
      *
      * @typeParam EventType      - A key from your eventTypeMapSchema (e.g., 'rest' | 'http' | 'sqs' | 'step')
-     * @typeParam EventSchema    - Optional Zod schema validated BEFORE the handler (refines event shape)
-     * @typeParam ResponseSchema - Optional Zod schema validated AFTER the handler (refines response shape)
-     * @param options - per‑function configuration (method/basePath/httpContexts for HTTP; serverless extras for non‑HTTP)
+     * @typeParam EventSchema    - Optional Zod schema validated BEFORE the handler (refines event shape)   * @typeParam ResponseSchema - Optional Zod schema validated AFTER the handler (refines response shape)   * @param options - per‑function configuration (method/basePath/httpContexts for HTTP; serverless extras for non‑HTTP)
      * @returns a per‑function API: { handler(business), openapi(baseOperation), serverless(extras) }
      */
     defineFunction(options) {