feat(sdk): typed request options and per-call transport overrides

codegen/src/api.ts

@@ -27,7 +27,7 @@ export async function generateIndex(
 
   export type { APIConfig } from './client'
   export { APIError, SumUpError } from './core'
-  export type { FetchParams } from './core'
+  export type { RequestOptions } from './core'
   export * from './types'
   `);
 

codegen/src/core.ts

@@ -33,20 +33,31 @@ export class APIResource {
 // biome-ignore lint/suspicious/noExplicitAny: any, but only for tests
 type QueryParams = Record<string, any>;
 
+type HTTPMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
 /**
- * Params that get passed to \`fetch\`. This ends up as an optional second
- * argument to each generated request method. Properties are a subset of
- * \`RequestInit\`.
+ * SDK-specific options that can be passed to any generated request method.
  */
-export type FetchParams = Omit<RequestInit, "body" | "method">;
+export type RequestOptions = {
+  /**
+   * Optional bearer authorization value to apply to the request, for example
+   * \`Bearer <access-token>\`. When provided, it overrides any default
+   * Authorization header configured on the client.
+   */
+  authorization?: string;
+  headers?: HeadersInit;
+  host?: string;
+  maxRetries?: number;
+  signal?: AbortSignal | null;
+  timeout?: number;
+};
 
 /** All arguments to \`request()\` */
-export type FullParams = FetchParams & {
+export type FullRequestOptions = RequestOptions & {
   path: string;
   query?: QueryParams;
   body?: unknown;
-  host?: string;
-  method?: string;
+  method?: HTTPMethod;
 };
 
 export class SumUpError extends Error {}

codegen/src/resource.ts

@@ -9,7 +9,6 @@ import {
   iterPathConfig,
   responseSchema,
 } from "./base";
-import type { FileWriter } from "./io";
 import { fileWriter } from "./io";
 import { schemaNameToTypeName, schemaToTypes } from "./schema";
 import {
@@ -66,7 +65,7 @@ export async function generateResource(
   const collectorWriter = {
     w() {},
     w0() {},
-  } as unknown as FileWriter;
+  };
 
   const resolveResponseObject = (
     response: OpenAPIV3_1.ResponseObject | OpenAPIV3_1.ReferenceObject,
@@ -180,11 +179,10 @@ export async function generateResource(
       );
   }
 
-  writer.w(`
-// Code generated by @sumup/sumup-ts-codegen. DO NOT EDIT.
-
-import { APIResource, type APIPromise, type FetchParams } from "../../core";
-`);
+  writer.w("// Code generated by @sumup/sumup-ts-codegen. DO NOT EDIT.\n");
+  writer.w(
+    'import { APIResource, type APIPromise, type RequestOptions } from "../../core";',
+  );
 
   const sortedSharedTypes = [...usedSharedTypes].sort((a, b) =>
     a > b ? 1 : -1,
@@ -316,6 +314,7 @@ export class ${resourceClassName} extends APIResource {`);
       writer.w(comment);
     }
 
+    const body = getRequestBody(opId, methodSpec);
     writer.w0(`${methodName}(`);
 
     if (pathParams.length > 0) {
@@ -327,7 +326,6 @@ export class ${resourceClassName} extends APIResource {`);
       }
     }
 
-    const body = getRequestBody(opId, methodSpec);
     if (body) {
       writer.w0(`body${body.required ? "" : "?"}: ${body.typeName}, `);
     }
@@ -338,7 +336,7 @@ export class ${resourceClassName} extends APIResource {`);
       writer.w0(`: ${queryParamsType(methodNameType)}, `);
     }
 
-    writer.w(`params?: FetchParams): APIPromise<${successType}, ${errorTypeName}> {
+    writer.w(`options?: RequestOptions): APIPromise<${successType}, ${errorTypeName}> {
          return this._client.${method}<${successType}, ${errorTypeName}>({
            path: ${pathToTemplateStr(path)},`);
     if (methodSpec.requestBody) {
@@ -347,7 +345,7 @@ export class ${resourceClassName} extends APIResource {`);
     if (queryParams.length > 0) {
       writer.w("  query,");
     }
-    writer.w(`  ...params,
+    writer.w(`  ...options,
          })
       }\n`);
   }

examples/checkout/index.ts

@@ -5,12 +5,6 @@ const client = new SumUp({
 });
 
 async function main() {
-  const merchant = await client.merchant.get();
-  console.info({ merchant });
-
-  const merchant2 = await client.merchant.get().withResponse();
-  console.info({ merchant2 });
-
   const merchantCode = process.env.SUMUP_MERCHANT_CODE;
   if (!merchantCode) {
     console.warn(
@@ -19,6 +13,12 @@ async function main() {
     return;
   }
 
+  const merchant = await client.merchants.get(merchantCode);
+  console.info({ merchant });
+
+  const merchant2 = await client.merchants.get(merchantCode).withResponse();
+  console.info({ merchant2 });
+
   const request: CheckoutCreateRequest = {
     amount: 19,
     checkout_reference: "CO746453",

sdk/README.md

@@ -46,8 +46,8 @@ const sumup = require('@sumup/sdk')({
   apiKey: 'sup_sk_MvxmLOl0...'
 });
 
-sumup.merchant.get()
-  .then(merchant => console.info(merchant))
+sumup.checkouts.list()
+  .then(checkouts => console.info(checkouts))
   .catch(error => console.error(error));
 ```
 
@@ -60,10 +60,29 @@ const client = new SumUp({
   apiKey: 'sup_sk_MvxmLOl0...',
 });
 
-const merchant = await client.merchant.get();
+const merchantCode = process.env.SUMUP_MERCHANT_CODE!;
+const merchant = await client.merchants.get(merchantCode);
 console.info(merchant);
 ```
 
+Per-request options are available as the last argument to any SDK call. For
+example, you can override authorization, timeout, retries, or headers for a
+single request:
+
+```ts
+await client.checkouts.list(undefined, {
+  timeout: 5_000,
+});
+
+await client.merchants.get(merchantCode, {
+  authorization: `Bearer ${accessToken}`,
+  headers: {
+    "x-request-id": "req_123",
+  },
+  maxRetries: 1,
+});
+```
+
 ## Examples
 
 Examples require an API key and your merchant code. You can run the examples using: