diff --git a/.changeset/brave-mirrors-design.md b/.changeset/brave-mirrors-design.md deleted file mode 100644 index 389d953028..0000000000 --- a/.changeset/brave-mirrors-design.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@vue-storefront/sdk": patch ---- - -[CHANGED] SDK extension allows now to override module methods in `extend` property. diff --git a/.changeset/silver-squids-switch.md b/.changeset/silver-squids-switch.md deleted file mode 100644 index 630589d6f1..0000000000 --- a/.changeset/silver-squids-switch.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@vue-storefront/sdk": minor ---- - -[ADDED] New SDK module - `middlewareModule`. It is a recommended way to communicate with the Server Middleware. diff --git a/docs/content/4.sdk/4.api/sdk.api.json b/docs/content/4.sdk/4.api/sdk.api.json index 971a1db9ae..039376f937 100644 --- a/docs/content/4.sdk/4.api/sdk.api.json +++ b/docs/content/4.sdk/4.api/sdk.api.json @@ -207,6 +207,32 @@ "endIndex": 4 } }, + { + "kind": "TypeAlias", + "canonicalReference": "@vue-storefront/sdk!BaseConfig:type", + "docComment": "/**\n * Base configuration object for HTTP requests. It includes essential configurations like the HTTP method.\n *\n * @remarks\n *\n * This type serves as a base for more detailed configuration objects by specifying the method of the HTTP request.\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export type BaseConfig = " + }, + { + "kind": "Content", + "text": "{\n method?: \"GET\" | \"POST\";\n}" + }, + { + "kind": "Content", + "text": ";" + } + ], + "fileUrlPath": "src/modules/middlewareModule/types.ts", + "releaseTag": "Public", + "name": "BaseConfig", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 2 + } + }, { "kind": "Function", "canonicalReference": "@vue-storefront/sdk!buildModule:function(1)", @@ -307,7 +333,7 @@ "text": ";" } ], - "fileUrlPath": "src/module/buildModule.ts", + "fileUrlPath": "src/modules/buildModule.ts", "returnTypeTokenRange": { "startIndex": 20, "endIndex": 21 @@ -496,7 +522,7 @@ "text": ";" } ], - "fileUrlPath": "src/module/buildModule.ts", + "fileUrlPath": "src/modules/buildModule.ts", "returnTypeTokenRange": { "startIndex": 20, "endIndex": 21 @@ -585,6 +611,46 @@ ], "name": "buildModule" }, + { + "kind": "TypeAlias", + "canonicalReference": "@vue-storefront/sdk!ComputedConfig:type", + "docComment": "/**\n * Computed configuration for HTTP requests, derived from `RequestConfig`. Normalizes header values to strings for consistent request formatting.\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export type ComputedConfig = " + }, + { + "kind": "Reference", + "text": "BaseConfig", + "canonicalReference": "@vue-storefront/sdk!BaseConfig:type" + }, + { + "kind": "Content", + "text": " & {\n headers?: " + }, + { + "kind": "Reference", + "text": "Record", + "canonicalReference": "!Record:type" + }, + { + "kind": "Content", + "text": ";\n}" + }, + { + "kind": "Content", + "text": ";" + } + ], + "fileUrlPath": "src/modules/middlewareModule/types.ts", + "releaseTag": "Public", + "name": "ComputedConfig", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 5 + } + }, { "kind": "TypeAlias", "canonicalReference": "@vue-storefront/sdk!Connector:type", @@ -625,6 +691,129 @@ "endIndex": 5 } }, + { + "kind": "TypeAlias", + "canonicalReference": "@vue-storefront/sdk!EndpointsConstraint:type", + "docComment": "/**\n * Represents the constraint for API endpoint functions within the SDK. Each endpoint function must return a Promise, allowing for asynchronous operations.\n *\n * @example\n * ```typescript\n * // Definition of an API endpoint structure\n * type Endpoints = {\n * getUser: ({ id: string }) => Promise;\n * createUser: (userDetails: CreateUserDetails) => Promise;\n * };\n * ```\n *\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export type EndpointsConstraint = " + }, + { + "kind": "Content", + "text": "{\n [key: string]: " + }, + { + "kind": "Reference", + "text": "AnyFunction", + "canonicalReference": "@vue-storefront/sdk!AnyFunction:type" + }, + { + "kind": "Content", + "text": ";\n}" + }, + { + "kind": "Content", + "text": ";" + } + ], + "fileUrlPath": "src/modules/middlewareModule/types.ts", + "releaseTag": "Public", + "name": "EndpointsConstraint", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 4 + } + }, + { + "kind": "TypeAlias", + "canonicalReference": "@vue-storefront/sdk!ErrorHandler:type", + "docComment": "/**\n * Defines a generic error handler function type. This abstraction allows for custom error handling logic, which can be implemented by the consumer of the HTTP client.\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export type ErrorHandler = " + }, + { + "kind": "Content", + "text": "(context: " + }, + { + "kind": "Reference", + "text": "ErrorHandlerContext", + "canonicalReference": "@vue-storefront/sdk!ErrorHandlerContext:type" + }, + { + "kind": "Content", + "text": ") => " + }, + { + "kind": "Reference", + "text": "Promise", + "canonicalReference": "!Promise:interface" + }, + { + "kind": "Content", + "text": "" + }, + { + "kind": "Content", + "text": ";" + } + ], + "fileUrlPath": "src/modules/middlewareModule/types.ts", + "releaseTag": "Public", + "name": "ErrorHandler", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 6 + } + }, + { + "kind": "TypeAlias", + "canonicalReference": "@vue-storefront/sdk!ErrorHandlerContext:type", + "docComment": "/**\n * Provides context for error handling, encapsulating details relevant to the failed HTTP request.\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export type ErrorHandlerContext = " + }, + { + "kind": "Content", + "text": "{\n error: unknown;\n methodName: string;\n url: string;\n params: unknown[];\n config: " + }, + { + "kind": "Reference", + "text": "ComputedConfig", + "canonicalReference": "@vue-storefront/sdk!ComputedConfig:type" + }, + { + "kind": "Content", + "text": ";\n httpClient: " + }, + { + "kind": "Reference", + "text": "HTTPClient", + "canonicalReference": "@vue-storefront/sdk!HTTPClient:type" + }, + { + "kind": "Content", + "text": ";\n}" + }, + { + "kind": "Content", + "text": ";" + } + ], + "fileUrlPath": "src/modules/middlewareModule/types.ts", + "releaseTag": "Public", + "name": "ErrorHandlerContext", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 6 + } + }, { "kind": "TypeAlias", "canonicalReference": "@vue-storefront/sdk!EventCallback:type", @@ -892,6 +1081,43 @@ "endIndex": 9 } }, + { + "kind": "Variable", + "canonicalReference": "@vue-storefront/sdk!getRequestSender:var", + "docComment": "/**\n * Generates a `RequestSender` function configured according to the provided options.\n *\n * @remarks\n *\n * This function abstracts away the details of constructing request URLs, merging configurations, handling errors, and executing HTTP requests.\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "getRequestSender: " + }, + { + "kind": "Content", + "text": "(options: " + }, + { + "kind": "Reference", + "text": "Options", + "canonicalReference": "@vue-storefront/sdk!Options:type" + }, + { + "kind": "Content", + "text": ") => " + }, + { + "kind": "Reference", + "text": "RequestSender", + "canonicalReference": "@vue-storefront/sdk!RequestSender:type" + } + ], + "fileUrlPath": "src/modules/middlewareModule/utils/getRequestSender.ts", + "isReadonly": true, + "releaseTag": "Public", + "name": "getRequestSender", + "variableTypeTokenRange": { + "startIndex": 1, + "endIndex": 5 + } + }, { "kind": "Variable", "canonicalReference": "@vue-storefront/sdk!handleError:var", @@ -929,6 +1155,50 @@ "endIndex": 5 } }, + { + "kind": "TypeAlias", + "canonicalReference": "@vue-storefront/sdk!HTTPClient:type", + "docComment": "/**\n * A customizable HTTP client function for making HTTP requests.\n *\n * @remarks\n *\n * This type represents a flexible interface for HTTP clients within the SDK, allowing for customization and substitution of different HTTP request mechanisms (e.g., Fetch API, Axios).\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export type HTTPClient = " + }, + { + "kind": "Content", + "text": "(\nurl: string, \nparams: unknown[], \nconfig?: " + }, + { + "kind": "Reference", + "text": "ComputedConfig", + "canonicalReference": "@vue-storefront/sdk!ComputedConfig:type" + }, + { + "kind": "Content", + "text": ") => " + }, + { + "kind": "Reference", + "text": "Promise", + "canonicalReference": "!Promise:interface" + }, + { + "kind": "Content", + "text": "" + }, + { + "kind": "Content", + "text": ";" + } + ], + "fileUrlPath": "src/modules/middlewareModule/types.ts", + "releaseTag": "Public", + "name": "HTTPClient", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 6 + } + }, { "kind": "TypeAlias", "canonicalReference": "@vue-storefront/sdk!InitFunction:type", @@ -1503,6 +1773,180 @@ "endIndex": 2 } }, + { + "kind": "TypeAlias", + "canonicalReference": "@vue-storefront/sdk!MethodConfig:type", + "docComment": "/**\n * Configuration specific to a method, merging `RequestConfig` with an internal flag. Indicates that the configuration is ready for making a request.\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export type MethodConfig = " + }, + { + "kind": "Reference", + "text": "RequestConfig", + "canonicalReference": "@vue-storefront/sdk!RequestConfig:type" + }, + { + "kind": "Content", + "text": " & {\n [" + }, + { + "kind": "Reference", + "text": "isConfig", + "canonicalReference": "@vue-storefront/sdk!~isConfig:var" + }, + { + "kind": "Content", + "text": "]: boolean;\n}" + }, + { + "kind": "Content", + "text": ";" + } + ], + "fileUrlPath": "src/modules/middlewareModule/types.ts", + "releaseTag": "Public", + "name": "MethodConfig", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 5 + } + }, + { + "kind": "TypeAlias", + "canonicalReference": "@vue-storefront/sdk!Methods:type", + "docComment": "/**\n * Final type for the SDK methods.\n *\n * It requires the `Endpoints` interface to be provided.\n *\n * Based on this interface it will generate the methods with the correct parameters and return types.\n *\n * To each endpoint, it will add the `config` parameter with the `MethodConfig` type.\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export type Methods = " + }, + { + "kind": "Content", + "text": "{\n [Key in keyof Endpoints]: (...params: [..." + }, + { + "kind": "Reference", + "text": "Parameters", + "canonicalReference": "!Parameters:type" + }, + { + "kind": "Content", + "text": ", config?: " + }, + { + "kind": "Reference", + "text": "MethodConfig", + "canonicalReference": "@vue-storefront/sdk!MethodConfig:type" + }, + { + "kind": "Content", + "text": "]) => " + }, + { + "kind": "Reference", + "text": "ReturnType", + "canonicalReference": "!ReturnType:type" + }, + { + "kind": "Content", + "text": ";\n}" + }, + { + "kind": "Content", + "text": ";" + } + ], + "fileUrlPath": "src/modules/middlewareModule/types.ts", + "releaseTag": "Public", + "name": "Methods", + "typeParameters": [ + { + "typeParameterName": "Endpoints", + "constraintTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "defaultTypeTokenRange": { + "startIndex": 0, + "endIndex": 0 + } + } + ], + "typeTokenRange": { + "startIndex": 3, + "endIndex": 10 + } + }, + { + "kind": "Variable", + "canonicalReference": "@vue-storefront/sdk!middlewareModule:var", + "docComment": "/**\n * `middlewareModule` is allowing to communicate with the Server Middleware API.\n *\n * It generates the methods to communicate with the API based on the provided endpoints interface.\n *\n * @example\n *\n * Setup:\n * ```ts\n * import { createSdk } from \"@vue-storefront/next\";\n * import type { SapccEndpoints } from \"../storefront-middleware/types\";\n *\n * export const { getSdk } = createSdk(options, ({ buildModule, middlewareModule }) => ({\n * sapcc: buildModule(middlewareModule, {\n * apiUrl: \"http://localhost:4000/sapcc\",\n * }),\n * }));\n * ```\n *\n * It also exposes the `context` with the `requestSender` to allow to use it directly in extensions.\n *\n * @example\n *\n * Usage:\n * ```ts\n * import { createSdk } from \"@vue-storefront/next\";\n * import type { SapccEndpoints } from \"../storefront-middleware/types\";\n *\n * const extension = (extensionOptions, { methods, context }) => ({\n * extend: {\n * async newMethod(params) {\n * const response = await context.requestSender(\"customMethod\", [params]);\n * const products = await methods.getProducts(params);\n * return { ...response, ...products };\n * }\n * }\n * });\n *\n * export const { getSdk } = createSdk(options, ({ buildModule, middlewareModule }) => ({\n * sapcc: buildModule(middlewareModule, {\n * apiUrl: \"http://localhost:4000/sapcc\",\n * }, extension),\n * }));\n * ```\n *\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "middlewareModule: " + }, + { + "kind": "Content", + "text": "(options: " + }, + { + "kind": "Reference", + "text": "Options", + "canonicalReference": "@vue-storefront/sdk!Options:type" + }, + { + "kind": "Content", + "text": ") => {\n connector: import(\"./types\")." + }, + { + "kind": "Reference", + "text": "Methods", + "canonicalReference": "@vue-storefront/sdk!Methods:type" + }, + { + "kind": "Content", + "text": ";\n context: {\n requestSender: import(\"./types\")." + }, + { + "kind": "Reference", + "text": "RequestSender", + "canonicalReference": "@vue-storefront/sdk!RequestSender:type" + }, + { + "kind": "Content", + "text": ";\n };\n}" + } + ], + "fileUrlPath": "src/modules/middlewareModule/module.ts", + "isReadonly": true, + "releaseTag": "Public", + "name": "middlewareModule", + "variableTypeTokenRange": { + "startIndex": 1, + "endIndex": 10 + } + }, { "kind": "TypeAlias", "canonicalReference": "@vue-storefront/sdk!Module:type", @@ -1732,6 +2176,189 @@ "endIndex": 3 } }, + { + "kind": "TypeAlias", + "canonicalReference": "@vue-storefront/sdk!Options:type", + "docComment": "/**\n * Options for the `middlewareModule`.\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export type Options = " + }, + { + "kind": "Content", + "text": "{\n apiUrl: string;\n ssrApiUrl?: string;\n httpClient?: " + }, + { + "kind": "Reference", + "text": "HTTPClient", + "canonicalReference": "@vue-storefront/sdk!HTTPClient:type" + }, + { + "kind": "Content", + "text": ";\n defaultRequestConfig?: " + }, + { + "kind": "Reference", + "text": "RequestConfig", + "canonicalReference": "@vue-storefront/sdk!RequestConfig:type" + }, + { + "kind": "Content", + "text": ";\n errorHandler?: " + }, + { + "kind": "Reference", + "text": "ErrorHandler", + "canonicalReference": "@vue-storefront/sdk!ErrorHandler:type" + }, + { + "kind": "Content", + "text": ";\n}" + }, + { + "kind": "Content", + "text": ";" + } + ], + "fileUrlPath": "src/modules/middlewareModule/types.ts", + "releaseTag": "Public", + "name": "Options", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 8 + } + }, + { + "kind": "Variable", + "canonicalReference": "@vue-storefront/sdk!prepareConfig:var", + "docComment": "/**\n * Prepare the config for the request. It's used to differentiate the method config from the params.\n *\n * @example\n *\n * Usage\n * ```ts\n * import { prepareConfig } from \"@vue-storefront/sdk\";\n *\n * const products = sdk.commerce.getProducts(params, prepareConfig({ method: \"GET\" }));\n * ```\n *\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "prepareConfig: " + }, + { + "kind": "Content", + "text": "(requestConfig: CustomConfig) => " + }, + { + "kind": "Reference", + "text": "MethodConfig", + "canonicalReference": "@vue-storefront/sdk!MethodConfig:type" + } + ], + "fileUrlPath": "src/modules/middlewareModule/utils/prepareConfig.ts", + "isReadonly": true, + "releaseTag": "Public", + "name": "prepareConfig", + "variableTypeTokenRange": { + "startIndex": 1, + "endIndex": 7 + } + }, + { + "kind": "TypeAlias", + "canonicalReference": "@vue-storefront/sdk!RequestConfig:type", + "docComment": "/**\n * User-defined configuration for HTTP requests, extending `BaseConfig`. Allows custom headers, supporting both strings and arrays of strings for header values.\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export type RequestConfig = " + }, + { + "kind": "Reference", + "text": "BaseConfig", + "canonicalReference": "@vue-storefront/sdk!BaseConfig:type" + }, + { + "kind": "Content", + "text": " & {\n headers?: " + }, + { + "kind": "Reference", + "text": "Record", + "canonicalReference": "!Record:type" + }, + { + "kind": "Content", + "text": ";\n}" + }, + { + "kind": "Content", + "text": ";" + } + ], + "fileUrlPath": "src/modules/middlewareModule/types.ts", + "releaseTag": "Public", + "name": "RequestConfig", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 5 + } + }, + { + "kind": "TypeAlias", + "canonicalReference": "@vue-storefront/sdk!RequestSender:type", + "docComment": "/**\n * Represents a function type for sending HTTP requests, abstracting the complexity of request configuration.\n *\n * @remarks\n *\n * This type is created via a factory function that configures it with common settings, such as base URLs and default headers.\n *\n * It simplifies making HTTP requests by handling URL construction, parameter serialization, and applying default and overridden configurations.\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export type RequestSender = " + }, + { + "kind": "Content", + "text": "(\nmethodName: string, \nparams: unknown[], \nconfig?: " + }, + { + "kind": "Reference", + "text": "RequestConfig", + "canonicalReference": "@vue-storefront/sdk!RequestConfig:type" + }, + { + "kind": "Content", + "text": ") => " + }, + { + "kind": "Reference", + "text": "Promise", + "canonicalReference": "!Promise:interface" + }, + { + "kind": "Content", + "text": "" + }, + { + "kind": "Content", + "text": ";" + } + ], + "fileUrlPath": "src/modules/middlewareModule/types.ts", + "releaseTag": "Public", + "name": "RequestSender", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 6 + } + }, { "kind": "TypeAlias", "canonicalReference": "@vue-storefront/sdk!SDKApi:type", @@ -1752,7 +2379,25 @@ }, { "kind": "Content", - "text": "{\n [ExtensionName in keyof Config]: {\n +readonly [Method in keyof Config[ExtensionName][\"connector\"] | keyof Config[ExtensionName][\"override\"]]: Method extends keyof Config[ExtensionName][\"override\"] ? Config[ExtensionName][\"override\"][Method] : Config[ExtensionName][\"connector\"][Method];\n } & {\n +readonly [Method in keyof Config[ExtensionName][\"extend\"]]: Config[ExtensionName][\"extend\"][Method];\n };\n} & {\n +readonly [ExtensionName in keyof Config]: {\n utils: {\n +readonly [Method in keyof Config[ExtensionName][\"utils\"]]: Config[ExtensionName][\"utils\"][Method];\n };\n };\n}" + "text": "{\n [ExtensionName in keyof Config]: Config[ExtensionName][\"extend\"] & " + }, + { + "kind": "Reference", + "text": "Omit", + "canonicalReference": "!Omit:type" + }, + { + "kind": "Content", + "text": " & " + }, + { + "kind": "Reference", + "text": "Omit", + "canonicalReference": "!Omit:type" + }, + { + "kind": "Content", + "text": ";\n} & {\n +readonly [ExtensionName in keyof Config]: {\n utils: {\n +readonly [Method in keyof Config[ExtensionName][\"utils\"]]: Config[ExtensionName][\"utils\"][Method];\n };\n };\n}" }, { "kind": "Content", @@ -1777,7 +2422,7 @@ ], "typeTokenRange": { "startIndex": 3, - "endIndex": 4 + "endIndex": 8 } }, { diff --git a/docs/content/4.sdk/5.reference/change-log.md b/docs/content/4.sdk/5.reference/change-log.md index 456072f85d..ac6df6eb5e 100644 --- a/docs/content/4.sdk/5.reference/change-log.md +++ b/docs/content/4.sdk/5.reference/change-log.md @@ -1,5 +1,15 @@ # Change log +## 1.4.0 + +### Minor Changes + +- **[ADDED]** New SDK module - `middlewareModule`. It is a recommended way to communicate with the Server Middleware. + +### Patch Changes + +- **[CHANGED]** SDK extension allows now to override module methods in `extend` property. + ## 1.3.4 ### Patch Changes diff --git a/packages/sdk/CHANGELOG.md b/packages/sdk/CHANGELOG.md index 456072f85d..ac6df6eb5e 100644 --- a/packages/sdk/CHANGELOG.md +++ b/packages/sdk/CHANGELOG.md @@ -1,5 +1,15 @@ # Change log +## 1.4.0 + +### Minor Changes + +- **[ADDED]** New SDK module - `middlewareModule`. It is a recommended way to communicate with the Server Middleware. + +### Patch Changes + +- **[CHANGED]** SDK extension allows now to override module methods in `extend` property. + ## 1.3.4 ### Patch Changes diff --git a/packages/sdk/package.json b/packages/sdk/package.json index d5f4e0eaa1..6c6473f1ed 100644 --- a/packages/sdk/package.json +++ b/packages/sdk/package.json @@ -1,7 +1,7 @@ { "name": "@vue-storefront/sdk", "license": "MIT", - "version": "1.3.4", + "version": "1.4.0", "main": "lib/index.cjs.js", "module": "lib/index.es.js", "types": "lib/index.d.ts",