remove built in webhook response builder

.changeset/new-paws-win.md

@@ -0,0 +1,37 @@
+---
+"@saleor/app-sdk": major
+---
+
+Removed `ctx.buildResponse` parameter from SyncWebhookHandler ctx and replace with standalone `buildSyncWebhookResponsePayload` function
+
+Before
+
+```typescript
+
+new SaleorSyncWebhook(...).createHandler(
+  req, res, ctx
+) {
+
+  const typeSafePayload = ctx.buildResponse({
+    // this must be valid response
+  })
+}
+```
+
+After
+
+```typescript
+import { buildSyncWebhookResponsePayload } from "@saleor/app-sdk/handlers/shared";
+
+new SaleorSyncWebhook(...).createHandler(
+  req, res, ctx
+)
+{
+
+  const typeSafePayload = buildSyncWebhookResponsePayload<"ORDER_CALCULATE_TAXES">({
+    // this must be valid shape
+  })
+}
+```
+
+This change reduces complexity of TypeScript generics and make it easier to build abstractions on top of built-in handlers

src/handlers/platforms/aws-lambda/saleor-webhooks/saleor-sync-webhook.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-import { FormatWebhookErrorResult } from "@/handlers/shared";
+import { buildSyncWebhookResponsePayload, FormatWebhookErrorResult } from "@/handlers/shared";
 import { SaleorWebhookValidator } from "@/handlers/shared/saleor-webhook-validator";
 import { MockAPL } from "@/test-utils/mock-apl";
 
@@ -27,20 +27,20 @@ describe("AWS Lambda SaleorSyncWebhook", () => {
     it("returns valid URL when baseUrl has Lambda stage", () => {
       const webhook = new SaleorSyncWebhook(webhookConfig);
       expect(webhook.getWebhookManifest("https://aws-lambda.com/prod").targetUrl).toBe(
-        "https://aws-lambda.com/prod/api/webhooks/checkout-calculate-taxes"
+        "https://aws-lambda.com/prod/api/webhooks/checkout-calculate-taxes",
       );
       expect(webhook.getWebhookManifest("https://aws-lambda.com/prod/").targetUrl).toBe(
-        "https://aws-lambda.com/prod/api/webhooks/checkout-calculate-taxes"
+        "https://aws-lambda.com/prod/api/webhooks/checkout-calculate-taxes",
       );
       expect(webhook.getWebhookManifest("https://aws-lambda.com/test").targetUrl).toBe(
-        "https://aws-lambda.com/test/api/webhooks/checkout-calculate-taxes"
+        "https://aws-lambda.com/test/api/webhooks/checkout-calculate-taxes",
       );
     });
 
     it("returns valid URL when baseURl doesn't have lambda stage ($default stage)", () => {
       const webhook = new SaleorSyncWebhook(webhookConfig);
       expect(webhook.getWebhookManifest("https://aws-lambda.com/").targetUrl).toBe(
-        "https://aws-lambda.com/api/webhooks/checkout-calculate-taxes"
+        "https://aws-lambda.com/api/webhooks/checkout-calculate-taxes",
       );
     });
 
@@ -50,16 +50,16 @@ describe("AWS Lambda SaleorSyncWebhook", () => {
         webhookPath: `/${webhookConfig.webhookPath}`,
       });
       expect(webhook.getWebhookManifest("https://aws-lambda.com/prod").targetUrl).toBe(
-        "https://aws-lambda.com/prod/api/webhooks/checkout-calculate-taxes"
+        "https://aws-lambda.com/prod/api/webhooks/checkout-calculate-taxes",
       );
       expect(webhook.getWebhookManifest("https://aws-lambda.com/prod/").targetUrl).toBe(
-        "https://aws-lambda.com/prod/api/webhooks/checkout-calculate-taxes"
+        "https://aws-lambda.com/prod/api/webhooks/checkout-calculate-taxes",
       );
       expect(webhook.getWebhookManifest("https://aws-lambda.com/test").targetUrl).toBe(
-        "https://aws-lambda.com/test/api/webhooks/checkout-calculate-taxes"
+        "https://aws-lambda.com/test/api/webhooks/checkout-calculate-taxes",
       );
       expect(webhook.getWebhookManifest("https://aws-lambda.com/").targetUrl).toBe(
-        "https://aws-lambda.com/api/webhooks/checkout-calculate-taxes"
+        "https://aws-lambda.com/api/webhooks/checkout-calculate-taxes",
       );
     });
   });
@@ -88,15 +88,15 @@ describe("AWS Lambda SaleorSyncWebhook", () => {
 
       const handler: AwsLambdaSyncWebhookHandler<Payload> = vi
         .fn()
-        .mockImplementation(async (_event, _context, ctx) => ({
+        .mockImplementation(async () => ({
           statusCode: 200,
           body: JSON.stringify(
-            ctx.buildResponse({
+            buildSyncWebhookResponsePayload<"CHECKOUT_CALCULATE_TAXES">({
               lines: [{ tax_rate: 8, total_net_amount: 10, total_gross_amount: 10.8 }],
               shipping_price_gross_amount: 2.16,
               shipping_tax_rate: 8,
               shipping_price_net_amount: 2,
-            })
+            }),
           ),
         }));
       const wrappedHandler = saleorSyncWebhook.createHandler(handler);

src/handlers/platforms/aws-lambda/saleor-webhooks/saleor-sync-webhook.ts

@@ -1,34 +1,28 @@
-import { SyncWebhookInjectedContext } from "@/handlers/shared";
-import { buildSyncWebhookResponsePayload } from "@/handlers/shared/sync-webhook-response-builder";
 import { SyncWebhookEventType } from "@/types";
 
 import { AWSLambdaHandler } from "../platform-adapter";
 import { AwsLambdaWebhookHandler, SaleorWebApiWebhook, WebhookConfig } from "./saleor-webhook";
 
 export type AwsLambdaSyncWebhookHandler<
   TPayload,
-  TEvent extends SyncWebhookEventType = SyncWebhookEventType,
-> = AwsLambdaWebhookHandler<TPayload, SyncWebhookInjectedContext<TEvent>>;
+> = AwsLambdaWebhookHandler<TPayload>;
 
 export class SaleorSyncWebhook<
   TPayload = unknown,
   TEvent extends SyncWebhookEventType = SyncWebhookEventType,
-> extends SaleorWebApiWebhook<TPayload, SyncWebhookInjectedContext<TEvent>> {
+> extends SaleorWebApiWebhook<TPayload> {
   readonly event: TEvent;
 
   protected readonly eventType = "sync" as const;
 
-  protected extraContext = {
-    buildResponse: buildSyncWebhookResponsePayload<TEvent>,
-  };
 
   constructor(configuration: WebhookConfig<TEvent>) {
     super(configuration);
 
     this.event = configuration.event;
   }
 
-  createHandler(handlerFn: AwsLambdaSyncWebhookHandler<TPayload, TEvent>): AWSLambdaHandler {
+  createHandler(handlerFn: AwsLambdaSyncWebhookHandler<TPayload>): AWSLambdaHandler {
     return super.createHandler(handlerFn);
   }
 }

src/handlers/platforms/aws-lambda/saleor-webhooks/saleor-webhook.ts

@@ -16,21 +16,21 @@ export type WebhookConfig<Event = AsyncWebhookEventType | SyncWebhookEventType>
   GenericWebhookConfig<AwsLambdaHandlerInput, Event>;
 
 /** Function type provided by consumer in `SaleorWebApiWebhook.createHandler` */
-export type AwsLambdaWebhookHandler<TPayload = unknown, TExtras = {}> = (
+export type AwsLambdaWebhookHandler<TPayload = unknown> = (
   event: AwsLambdaHandlerInput,
   context: Context,
-  ctx: WebhookContext<TPayload> & TExtras
+  ctx: WebhookContext<TPayload>,
 ) => Promise<APIGatewayProxyStructuredResultV2> | APIGatewayProxyStructuredResultV2;
 
-export abstract class SaleorWebApiWebhook<
-  TPayload = unknown,
-  TExtras extends Record<string, unknown> = {}
-> extends GenericSaleorWebhook<AwsLambdaHandlerInput, TPayload, TExtras> {
+export abstract class SaleorWebApiWebhook<TPayload = unknown> extends GenericSaleorWebhook<
+  AwsLambdaHandlerInput,
+  TPayload
+> {
   /**
    * Wraps provided function, to ensure incoming request comes from registered Saleor instance.
    * Also provides additional `context` object containing typed payload and request properties.
    */
-  createHandler(handlerFn: AwsLambdaWebhookHandler<TPayload, TExtras>): AWSLambdaHandler {
+  createHandler(handlerFn: AwsLambdaWebhookHandler<TPayload>): AWSLambdaHandler {
     return async (event, context) => {
       const adapter = new AwsLambdaAdapter(event, context);
       const prepareRequestResult = await super.prepareRequest<AwsLambdaAdapter>(adapter);
@@ -41,7 +41,6 @@ export abstract class SaleorWebApiWebhook<
 
       debug("Incoming request validated. Call handlerFn");
       return handlerFn(event, context, {
-        ...(this.extraContext ?? ({} as TExtras)),
         ...prepareRequestResult.context,
       });
     };

src/handlers/platforms/fetch-api/saleor-webhooks/saleor-sync-webhook.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-import { FormatWebhookErrorResult } from "@/handlers/shared";
+import { buildSyncWebhookResponsePayload, FormatWebhookErrorResult } from "@/handlers/shared";
 import { SaleorWebhookValidator } from "@/handlers/shared/saleor-webhook-validator";
 import { MockAPL } from "@/test-utils/mock-apl";
 
@@ -41,17 +41,15 @@ describe("Web API SaleorSyncWebhook", () => {
       },
     });
 
-    const handler = vi
-      .fn<WebApiSyncWebhookHandler<Payload>>()
-      .mockImplementation((_request, ctx) => {
-        const responsePayload = ctx.buildResponse({
-          lines: [{ tax_rate: 8, total_net_amount: 10, total_gross_amount: 1.08 }],
-          shipping_price_gross_amount: 2,
-          shipping_tax_rate: 8,
-          shipping_price_net_amount: 1,
-        });
-        return new Response(JSON.stringify(responsePayload), { status: 200 });
+    const handler = vi.fn<WebApiSyncWebhookHandler<Payload>>().mockImplementation(() => {
+      const responsePayload = buildSyncWebhookResponsePayload<"ORDER_CALCULATE_TAXES">({
+        lines: [{ tax_rate: 8, total_net_amount: 10, total_gross_amount: 1.08 }],
+        shipping_price_gross_amount: 2,
+        shipping_tax_rate: 8,
+        shipping_price_net_amount: 1,
       });
+      return new Response(JSON.stringify(responsePayload), { status: 200 });
+    });
 
     const saleorSyncWebhook = new SaleorSyncWebhook<Payload>(webhookConfiguration);
 
@@ -70,7 +68,7 @@ describe("Web API SaleorSyncWebhook", () => {
         shipping_price_gross_amount: 2,
         shipping_tax_rate: 8,
         shipping_price_net_amount: 1,
-      })
+      }),
     );
   });
 

src/handlers/platforms/fetch-api/saleor-webhooks/saleor-sync-webhook.ts

@@ -1,34 +1,25 @@
-import { SyncWebhookInjectedContext } from "@/handlers/shared";
-import { buildSyncWebhookResponsePayload } from "@/handlers/shared/sync-webhook-response-builder";
 import { SyncWebhookEventType } from "@/types";
 
 import { WebApiHandler } from "../platform-adapter";
 import { SaleorWebApiWebhook, WebApiWebhookHandler, WebhookConfig } from "./saleor-webhook";
 
-export type WebApiSyncWebhookHandler<
-  TPayload,
-  TEvent extends SyncWebhookEventType = SyncWebhookEventType
-> = WebApiWebhookHandler<TPayload, SyncWebhookInjectedContext<TEvent>>;
+export type WebApiSyncWebhookHandler<TPayload> = WebApiWebhookHandler<TPayload>;
 
 export class SaleorSyncWebhook<
   TPayload = unknown,
-  TEvent extends SyncWebhookEventType = SyncWebhookEventType
-> extends SaleorWebApiWebhook<TPayload, SyncWebhookInjectedContext<TEvent>> {
+  TEvent extends SyncWebhookEventType = SyncWebhookEventType,
+> extends SaleorWebApiWebhook<TPayload> {
   readonly event: TEvent;
 
   protected readonly eventType = "sync" as const;
 
-  protected extraContext = {
-    buildResponse: buildSyncWebhookResponsePayload,
-  };
-
   constructor(configuration: WebhookConfig<TEvent>) {
     super(configuration);
 
     this.event = configuration.event;
   }
 
-  createHandler(handlerFn: WebApiSyncWebhookHandler<TPayload, TEvent>): WebApiHandler {
+  createHandler(handlerFn: WebApiSyncWebhookHandler<TPayload>): WebApiHandler {
     return super.createHandler(handlerFn);
   }
 }

src/handlers/platforms/next/saleor-webhooks/saleor-sync-webhook.test.ts

@@ -1,7 +1,7 @@
 import { createMocks } from "node-mocks-http";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-import { WebhookError } from "@/handlers/shared";
+import { buildSyncWebhookResponsePayload, WebhookError } from "@/handlers/shared";
 import { SaleorWebhookValidator } from "@/handlers/shared/saleor-webhook-validator";
 import { MockAPL } from "@/test-utils/mock-apl";
 
@@ -31,7 +31,7 @@ describe("Next.js SaleorSyncWebhook", () => {
       expect(manifest).toEqual(
         expect.objectContaining({
           targetUrl: `${baseUrl}/${validSyncWebhookConfiguration.webhookPath}`,
-        })
+        }),
       );
     });
 
@@ -66,8 +66,8 @@ describe("Next.js SaleorSyncWebhook", () => {
       });
 
       const saleorSyncWebhook = new SaleorSyncWebhook(validSyncWebhookConfiguration);
-      const testHandler: NextJsWebhookHandler = vi.fn().mockImplementation((_req, res, ctx) => {
-        const responsePayload = ctx.buildResponse({
+      const testHandler: NextJsWebhookHandler = vi.fn().mockImplementation((_req, res) => {
+        const responsePayload = buildSyncWebhookResponsePayload({
           lines: [{ tax_rate: 8, total_net_amount: 10, total_gross_amount: 1.08 }],
           shipping_price_gross_amount: 2,
           shipping_tax_rate: 8,
@@ -88,7 +88,7 @@ describe("Next.js SaleorSyncWebhook", () => {
           shipping_price_gross_amount: 2,
           shipping_tax_rate: 8,
           shipping_price_net_amount: 1,
-        })
+        }),
       );
     });
 

src/handlers/platforms/next/saleor-webhooks/saleor-sync-webhook.ts

@@ -1,35 +1,26 @@
 import { NextApiHandler } from "next";
 
-import { SyncWebhookInjectedContext } from "@/handlers/shared";
-import { buildSyncWebhookResponsePayload } from "@/handlers/shared/sync-webhook-response-builder";
 import { SyncWebhookEventType } from "@/types";
 
 import { NextJsWebhookHandler, SaleorWebhook, WebhookConfig } from "./saleor-webhook";
 
-export type NextJsSyncWebhookHandler<
-  TPayload,
-  TEvent extends SyncWebhookEventType = SyncWebhookEventType
-> = NextJsWebhookHandler<TPayload, SyncWebhookInjectedContext<TEvent>>;
+export type NextJsSyncWebhookHandler<TPayload> = NextJsWebhookHandler<TPayload>;
 
 export class SaleorSyncWebhook<
   TPayload = unknown,
-  TEvent extends SyncWebhookEventType = SyncWebhookEventType
-> extends SaleorWebhook<TPayload, SyncWebhookInjectedContext<TEvent>> {
+  TEvent extends SyncWebhookEventType = SyncWebhookEventType,
+> extends SaleorWebhook<TPayload> {
   readonly event: TEvent;
 
   protected readonly eventType = "sync" as const;
 
-  protected extraContext = {
-    buildResponse: buildSyncWebhookResponsePayload,
-  };
-
   constructor(configuration: WebhookConfig<TEvent>) {
     super(configuration);
 
     this.event = configuration.event;
   }
 
-  createHandler(handlerFn: NextJsSyncWebhookHandler<TPayload, TEvent>): NextApiHandler {
+  createHandler(handlerFn: NextJsSyncWebhookHandler<TPayload>): NextApiHandler {
     return super.createHandler(handlerFn);
   }
 }

src/handlers/shared/saleor-webhook.ts

@@ -1,7 +1,4 @@
-import { SyncWebhookEventType } from "@/types";
-
 import { AuthData } from "../../APL";
-import { buildSyncWebhookResponsePayload } from "./sync-webhook-response-builder";
 
 export const WebhookErrorCodeMap: Record<SaleorWebhookError, number> = {
   OTHER: 500,
@@ -58,10 +55,6 @@ export type WebhookContext<TPayload> = {
   schemaVersion: number | null;
 };
 
-export type SyncWebhookInjectedContext<TEvent extends SyncWebhookEventType> = {
-  buildResponse: typeof buildSyncWebhookResponsePayload<TEvent>;
-};
-
 export type FormatWebhookErrorResult = {
   code: number;
   body: string;

src/handlers/shared/sync-webhook-response-builder.ts

@@ -167,5 +167,5 @@ export type SyncWebhookResponsesMap = {
  * Identity function, but it works on Typescript level to pick right payload based on first param
  */
 export const buildSyncWebhookResponsePayload = <E extends SyncWebhookEventType>(
-  payload: SyncWebhookResponsesMap[E]
+  payload: SyncWebhookResponsesMap[E],
 ): SyncWebhookResponsesMap[E] => payload;