sst-http 1.3.0 → 1.3.3-beta.2

package/README.md

@@ -1,6 +1,6 @@
 # sst-http
 
-Decorator-based HTTP routing for [SST v3](https://sst.dev) that keeps your app on a single Lambda handler while still wiring routes directly into API Gateway. Build routes with NestJS-style decorators, secure them with Firebase JWT authorizers, and generate an infra-ready manifest from your source.
+Decorator-based HTTP routing and EventBridge helpers for SST v3. Keep a single Lambda for your API, scan routes into a manifest, and wire everything into API Gateway. The bus helpers let you subscribe handlers with `@On()` and publish events from anywhere.
 
 ## Install
 
@@ -8,13 +8,44 @@ Decorator-based HTTP routing for [SST v3](https://sst.dev) that keeps your app o
 pnpm add sst-http
 ```
 
-## Define Routes
+## Import style
 
-Create routed functions anywhere in your project – no controller classes required.
+You can keep using the root entrypoint, or import by domain:
+
+```ts
+import { createHandler, Get, Post } from "sst-http/http";
+import { On, publish } from "sst-http/bus";
+
+// Root entrypoint also works
+import { createHandler as createHttpHandler } from "sst-http";
+```
+
+## Examples
+
+The repo ships three SST v3 examples under `examples/`:
+
+- `examples/http`: four HTTP routes (path param, query string, JSON body, plus a ping route).
+- `examples/bus-publisher`: exposes `GET /` and publishes a `demo.created` event to the bus.
+- `examples/bus-receiver`: a single `@On("demo.created")` handler that receives the event.
+
+To run one of them:
+
+```bash
+cd examples/http
+pnpm install
+pnpm run routes:scan
+pnpm run dev
+```
+
+For the bus pair, you can deploy either example in any order since events target the default bus.
+
+## HTTP routes
+
+Create routed functions anywhere in your project—no controllers required.
 
 ```ts
 // src/routes/users.ts
-import { Get, Post, FirebaseAuth, json } from "sst-http";
+import { Get, Post, FirebaseAuth, json } from "sst-http/http";
 
 export class UserRoutes {
   @Get("/users/{id}")
@@ -34,18 +65,18 @@ export const getUser = UserRoutes.getUser;
 export const createUser = UserRoutes.createUser;
 ```
 
-Enable name-based inference once at bootstrap if you prefer omitting explicit path strings:
+Enable name-based inference if you prefer omitting explicit paths:
 
 ```ts
-import { configureRoutes } from "sst-http";
+import { configureRoutes } from "sst-http/http";
 
 configureRoutes({ inferPathFromName: true });
 ```
 
-Parameter decorators are available when you want granular control:
+### Parameter decorators
 
 ```ts
-import { Body, Post } from "sst-http";
+import { Body, Post } from "sst-http/http";
 import { z } from "zod/v4";
 
 const CreateTodo = z.object({ title: z.string().min(1) });
@@ -53,7 +84,6 @@ const CreateTodo = z.object({ title: z.string().min(1) });
 export class TodoRoutes {
   @Post("/todos")
   static createTodo(@Body(CreateTodo) payload: z.infer<typeof CreateTodo>) {
-    // payload is validated JSON
     return { statusCode: 201, body: JSON.stringify(payload) };
   }
 }
@@ -62,16 +92,16 @@ export const createTodo = TodoRoutes.createTodo;
 ```
 
 > **Note**
-> API Gateway route keys expect `{param}` placeholders. The router accepts either `{param}` or `:param` at runtime, but manifests and infra wiring emit `{param}` so your deployed routes line up with AWS.
+> API Gateway route keys expect `{param}` placeholders. The router accepts `{param}` or `:param` at runtime, but manifests and infra wiring emit `{param}` so your deployed routes line up with AWS.
 
-## Single Lambda Entry
+## Single Lambda entry
 
-All decorated modules register themselves on import. The single exported handler performs routing and response formatting for both REST and HTTP API Gateway payloads.
+All decorated modules register themselves on import. The handler handles routing for both REST and HTTP API Gateway payloads.
 
 ```ts
 // src/server.ts
 import "reflect-metadata";
-import { createHandler } from "sst-http";
+import { createHandler } from "sst-http/http";
 
 import "./routes/users";
 import "./routes/health";
@@ -79,25 +109,56 @@ import "./routes/health";
 export const handler = createHandler();
 ```
 
-Helpers such as `json()`, `text()`, and `noContent()` are available for concise responses, and thrown `HttpError` instances are turned into normalized JSON error payloads.
+Helpers such as `json()`, `text()`, and `noContent()` are available for concise responses. Throw `HttpError` to return a normalized JSON error payload.
+
+## Event bus
 
-## Scan & Manifest
+Use `@On()` to register EventBridge handlers and `publish()` to emit events.
 
-Use the CLI to inspect your source tree and materialize a routes manifest for infra wiring.
+```ts
+// src/events/user-events.ts
+import { On } from "sst-http/bus";
+
+export class UserEvents {
+  @On("user.created")
+  static async onUserCreated(detail: { id: string }) {
+    console.log("New user", detail.id);
+  }
+}
+
+export const onUserCreated = UserEvents.onUserCreated;
+```
+
+```ts
+import { publish } from "sst-http/bus";
+
+await publish("user.created", { id: "123" });
+```
+
+`publish()` signs requests with the current AWS credentials and requires `AWS_REGION`/`AWS_DEFAULT_REGION` in the environment.
+
+## Scan & manifest
+
+Use the CLI to inspect your source tree and materialize a manifest for infra wiring.
 
 ```bash
-pnpm sst-http scan --glob "src/routes/**/*.ts" --out routes.manifest.json
+pnpm sst-http scan --glob "src/**/*.ts" --out routes.manifest.json
 ```
 
-Pass `--infer-name` to map routes without explicit paths using the kebab-case function name (matching the runtime `configureRoutes({ inferPathFromName: true })`).
+Pass `--infer-name` to map routes without explicit paths using the kebab-case function name (matching `configureRoutes({ inferPathFromName: true })`). When `@On()` is used, events are emitted into the same manifest under `events`.
+
+## Firebase JWT authorizer
 
-## Firebase JWT Authorizer
+Mark a route with `@FirebaseAuth()` and the manifest records it as protected. The wiring utilities configure an API Gateway JWT authorizer using:
 
-Mark a route with `@FirebaseAuth()` and the manifest records it as protected. The core wiring function sets up an API Gateway JWT authorizer that points at your Firebase project (issuer `https://securetoken.google.com/<projectId>` and matching audience). Optional roles and optional-auth flags flow through to the adapter so you can fine-tune scopes.
+- Issuer: `https://securetoken.google.com/<projectId>`
+- Audience: `<projectId>`
 
-## Wire API Gateway
+Optional roles and optional-auth flags flow into the adapter so you can fine-tune scopes.
 
-`sst-http/infra` ships with a manifest-driven wiring utility plus adapters for HTTP API (ApiGatewayV2) and REST API (ApiGateway). The example below wires all routes to a single Lambda function inside `sst.config.ts`.
+## Wire API Gateway + EventBridge
+
+`sst-http/infra` ships with a manifest-driven wiring utility plus adapters for HTTP API (ApiGatewayV2) and REST API (ApiGateway). The example below wires all routes to a single Lambda function inside `sst.config.ts` and connects event subscriptions from the same manifest.
 
 ```ts
 // sst.config.ts
@@ -110,12 +171,12 @@ export default $config({
       loadRoutesManifest,
       wireApiFromManifest,
       httpApiAdapter,
+      createBus,
     } = await import("sst-http/infra");
 
     const manifest = loadRoutesManifest("routes.manifest.json");
     const { api, registerRoute, ensureJwtAuthorizer } = httpApiAdapter({ apiName: "Api" });
 
-    // Single Lambda for all routes
     const handler = new sst.aws.Function("Handler", {
       handler: "src/server.handler",
       runtime: "nodejs20.x",
@@ -123,11 +184,14 @@ export default $config({
       memory: "512 MB",
     });
 
+    const bus = createBus();
+
     wireApiFromManifest(manifest, {
       handler,
       firebaseProjectId: process.env.FIREBASE_PROJECT_ID!,
       registerRoute,
       ensureJwtAuthorizer,
+      buses: [bus],
     });
 
     return { ApiUrl: api.url };
@@ -137,9 +201,6 @@ export default $config({
 
 Swap in `restApiAdapter` if you prefer API Gateway REST APIs—the wiring contract is identical.
 
-> Tip
-> Set `FIREBASE_PROJECT_ID` in your environment when using `@FirebaseAuth()` so the JWT authorizer is configured correctly.
-
 ## Publishing
 
 ```bash
@@ -148,8 +209,6 @@ npm version patch
 pnpm run release
 ```
 
-The release script builds the ESM/CJS bundles via `tsup` before publishing.
-
 ## License
 
 MIT

package/dist/bus/index.cjs

@@ -0,0 +1,185 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/bus/index.ts
+var bus_exports = {};
+__export(bus_exports, {
+  On: () => On,
+  publish: () => publish
+});
+module.exports = __toCommonJS(bus_exports);
+
+// src/core/handler.ts
+function resolveHandler(target, propertyKey, descriptor) {
+  if (descriptor?.value && typeof descriptor.value === "function") {
+    return descriptor.value;
+  }
+  if (typeof target === "function" && propertyKey === void 0) {
+    return target;
+  }
+  if (target && propertyKey && typeof target[propertyKey] === "function") {
+    return target[propertyKey];
+  }
+  throw new Error("Unable to determine decorated function. Ensure decorators are applied to functions.");
+}
+
+// src/core/registry.ts
+var eventMeta = /* @__PURE__ */ new Map();
+function registerEvent(target, event) {
+  const handler = target;
+  const list = eventMeta.get(handler) ?? [];
+  list.push({ event });
+  eventMeta.set(handler, list);
+}
+
+// src/bus/decorators.ts
+function On(event) {
+  return (target, propertyKey, descriptor) => {
+    if (!event) {
+      throw new Error("@On() requires an event name.");
+    }
+    const handler = resolveHandler(target, propertyKey, descriptor);
+    registerEvent(handler, event);
+  };
+}
+
+// src/bus/event-bus.ts
+var import_node_crypto = require("crypto");
+var AWS_TARGET = "AWSEvents.PutEvents";
+var AWS_SERVICE = "events";
+var DEFAULT_SOURCE = "sst-http";
+async function publish(event, message) {
+  if (!event) {
+    throw new Error("publish() requires an event name.");
+  }
+  const payload = {
+    Entries: [
+      {
+        EventBusName: "default",
+        Source: DEFAULT_SOURCE,
+        DetailType: event,
+        Detail: JSON.stringify(message ?? null)
+      }
+    ]
+  };
+  console.log(payload);
+  await putEventsViaFetch(payload);
+}
+async function putEventsViaFetch(payload) {
+  const region = resolveRegion();
+  const creds = resolveCredentials();
+  const host = `events.${region}.amazonaws.com`;
+  const url = `https://${host}/`;
+  const body = JSON.stringify(payload);
+  const amzDate = toAmzDate(/* @__PURE__ */ new Date());
+  const dateStamp = amzDate.slice(0, 8);
+  const headers = {
+    "content-type": "application/x-amz-json-1.1",
+    "x-amz-date": amzDate,
+    "x-amz-target": AWS_TARGET,
+    host
+  };
+  if (creds.sessionToken) {
+    headers["x-amz-security-token"] = creds.sessionToken;
+  }
+  const signedHeaders = getSignedHeaders(headers);
+  const canonicalRequest = [
+    "POST",
+    "/",
+    "",
+    canonicalizeHeaders(headers),
+    signedHeaders,
+    sha256(body)
+  ].join("\n");
+  const scope = `${dateStamp}/${region}/${AWS_SERVICE}/aws4_request`;
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    amzDate,
+    scope,
+    sha256(canonicalRequest)
+  ].join("\n");
+  const signingKey = getSigningKey(creds.secretAccessKey, dateStamp, region, AWS_SERVICE);
+  const signature = hmac(signingKey, stringToSign);
+  const authorization = `AWS4-HMAC-SHA256 Credential=${creds.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      ...headers,
+      Authorization: authorization
+    },
+    body
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`EventBridge PutEvents failed: ${response.status} ${text}`);
+  }
+}
+function resolveRegion() {
+  const region = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION;
+  if (!region) {
+    throw new Error("AWS region is not set");
+  }
+  return region;
+}
+function resolveCredentials() {
+  const accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+  const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+  const sessionToken = process.env.AWS_SESSION_TOKEN;
+  if (!accessKeyId || !secretAccessKey) {
+    throw new Error("AWS credentials are not set");
+  }
+  return { accessKeyId, secretAccessKey, sessionToken };
+}
+function toAmzDate(date) {
+  const pad = (value) => value.toString().padStart(2, "0");
+  return [
+    date.getUTCFullYear(),
+    pad(date.getUTCMonth() + 1),
+    pad(date.getUTCDate()),
+    "T",
+    pad(date.getUTCHours()),
+    pad(date.getUTCMinutes()),
+    pad(date.getUTCSeconds()),
+    "Z"
+  ].join("");
+}
+function sha256(value) {
+  return (0, import_node_crypto.createHash)("sha256").update(value, "utf8").digest("hex");
+}
+function hmac(key, value) {
+  return (0, import_node_crypto.createHmac)("sha256", key).update(value, "utf8").digest("hex");
+}
+function getSigningKey(secret, date, region, service) {
+  const kDate = (0, import_node_crypto.createHmac)("sha256", `AWS4${secret}`).update(date, "utf8").digest();
+  const kRegion = (0, import_node_crypto.createHmac)("sha256", kDate).update(region, "utf8").digest();
+  const kService = (0, import_node_crypto.createHmac)("sha256", kRegion).update(service, "utf8").digest();
+  return (0, import_node_crypto.createHmac)("sha256", kService).update("aws4_request", "utf8").digest();
+}
+function canonicalizeHeaders(headers) {
+  return Object.keys(headers).map((key) => key.toLowerCase()).sort().map((key) => `${key}:${headers[key].trim()}
+`).join("");
+}
+function getSignedHeaders(headers) {
+  return Object.keys(headers).map((key) => key.toLowerCase()).sort().join(";");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  On,
+  publish
+});

package/dist/bus/index.d.cts

@@ -0,0 +1,7 @@
+import { L as LegacyDecorator } from '../handler-DaM4Racx.cjs';
+
+declare function On(event: string): LegacyDecorator;
+
+declare function publish(event: string, message: unknown): Promise<void>;
+
+export { On, publish };

package/dist/bus/index.d.ts

@@ -0,0 +1,7 @@
+import { L as LegacyDecorator } from '../handler-DaM4Racx.js';
+
+declare function On(event: string): LegacyDecorator;
+
+declare function publish(event: string, message: unknown): Promise<void>;
+
+export { On, publish };

package/dist/bus/index.js

@@ -0,0 +1,9 @@
+import {
+  On,
+  publish
+} from "../chunk-LLR3DQ65.js";
+import "../chunk-YMGEGOSD.js";
+export {
+  On,
+  publish
+};

package/dist/{chunk-5MOJ3SW6.js → chunk-5OUNKYO5.js}

@@ -1,4 +1,4 @@
-// src/paths.ts
+// src/http/paths.ts
 var API_GATEWAY_PARAM_RE = /(^|\/):([A-Za-z0-9_]+(?:[+*])?)(?=\/|$)/g;
 function normalizeRouterPath(path) {
   return path.replace(/\{([^/{}]+)\}/g, ":$1");

package/dist/chunk-LLR3DQ65.js

@@ -0,0 +1,140 @@
+import {
+  registerEvent,
+  resolveHandler
+} from "./chunk-YMGEGOSD.js";
+
+// src/bus/decorators.ts
+function On(event) {
+  return (target, propertyKey, descriptor) => {
+    if (!event) {
+      throw new Error("@On() requires an event name.");
+    }
+    const handler = resolveHandler(target, propertyKey, descriptor);
+    registerEvent(handler, event);
+  };
+}
+
+// src/bus/event-bus.ts
+import { createHash, createHmac } from "crypto";
+var AWS_TARGET = "AWSEvents.PutEvents";
+var AWS_SERVICE = "events";
+var DEFAULT_SOURCE = "sst-http";
+async function publish(event, message) {
+  if (!event) {
+    throw new Error("publish() requires an event name.");
+  }
+  const payload = {
+    Entries: [
+      {
+        EventBusName: "default",
+        Source: DEFAULT_SOURCE,
+        DetailType: event,
+        Detail: JSON.stringify(message ?? null)
+      }
+    ]
+  };
+  console.log(payload);
+  await putEventsViaFetch(payload);
+}
+async function putEventsViaFetch(payload) {
+  const region = resolveRegion();
+  const creds = resolveCredentials();
+  const host = `events.${region}.amazonaws.com`;
+  const url = `https://${host}/`;
+  const body = JSON.stringify(payload);
+  const amzDate = toAmzDate(/* @__PURE__ */ new Date());
+  const dateStamp = amzDate.slice(0, 8);
+  const headers = {
+    "content-type": "application/x-amz-json-1.1",
+    "x-amz-date": amzDate,
+    "x-amz-target": AWS_TARGET,
+    host
+  };
+  if (creds.sessionToken) {
+    headers["x-amz-security-token"] = creds.sessionToken;
+  }
+  const signedHeaders = getSignedHeaders(headers);
+  const canonicalRequest = [
+    "POST",
+    "/",
+    "",
+    canonicalizeHeaders(headers),
+    signedHeaders,
+    sha256(body)
+  ].join("\n");
+  const scope = `${dateStamp}/${region}/${AWS_SERVICE}/aws4_request`;
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    amzDate,
+    scope,
+    sha256(canonicalRequest)
+  ].join("\n");
+  const signingKey = getSigningKey(creds.secretAccessKey, dateStamp, region, AWS_SERVICE);
+  const signature = hmac(signingKey, stringToSign);
+  const authorization = `AWS4-HMAC-SHA256 Credential=${creds.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      ...headers,
+      Authorization: authorization
+    },
+    body
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`EventBridge PutEvents failed: ${response.status} ${text}`);
+  }
+}
+function resolveRegion() {
+  const region = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION;
+  if (!region) {
+    throw new Error("AWS region is not set");
+  }
+  return region;
+}
+function resolveCredentials() {
+  const accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+  const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+  const sessionToken = process.env.AWS_SESSION_TOKEN;
+  if (!accessKeyId || !secretAccessKey) {
+    throw new Error("AWS credentials are not set");
+  }
+  return { accessKeyId, secretAccessKey, sessionToken };
+}
+function toAmzDate(date) {
+  const pad = (value) => value.toString().padStart(2, "0");
+  return [
+    date.getUTCFullYear(),
+    pad(date.getUTCMonth() + 1),
+    pad(date.getUTCDate()),
+    "T",
+    pad(date.getUTCHours()),
+    pad(date.getUTCMinutes()),
+    pad(date.getUTCSeconds()),
+    "Z"
+  ].join("");
+}
+function sha256(value) {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function hmac(key, value) {
+  return createHmac("sha256", key).update(value, "utf8").digest("hex");
+}
+function getSigningKey(secret, date, region, service) {
+  const kDate = createHmac("sha256", `AWS4${secret}`).update(date, "utf8").digest();
+  const kRegion = createHmac("sha256", kDate).update(region, "utf8").digest();
+  const kService = createHmac("sha256", kRegion).update(service, "utf8").digest();
+  return createHmac("sha256", kService).update("aws4_request", "utf8").digest();
+}
+function canonicalizeHeaders(headers) {
+  return Object.keys(headers).map((key) => key.toLowerCase()).sort().map((key) => `${key}:${headers[key].trim()}
+`).join("");
+}
+function getSignedHeaders(headers) {
+  return Object.keys(headers).map((key) => key.toLowerCase()).sort().join(";");
+}
+
+export {
+  On,
+  publish
+};