@commercetools-frontend/sdk 0.0.0-CRAFT-1791-20251006162610

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) commercetools GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# @commercetools-frontend/sdk
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@commercetools-frontend/sdk"><img src="https://badgen.net/npm/v/@commercetools-frontend/sdk" alt="Latest release (latest dist-tag)" /></a> <a href="https://www.npmjs.com/package/@commercetools-frontend/sdk"><img src="https://badgen.net/npm/v/@commercetools-frontend/sdk/next" alt="Latest release (next dist-tag)" /></a> <a href="https://bundlephobia.com/result?p=@commercetools-frontend/sdk"><img src="https://badgen.net/bundlephobia/minzip/@commercetools-frontend/sdk" alt="Minified + GZipped size" /></a> <a href="https://github.com/commercetools/merchant-center-application-kit/blob/main/LICENSE"><img src="https://badgen.net/github/license/commercetools/merchant-center-application-kit" alt="GitHub license" /></a>
+</p>
+
+Tools for declarative fetching.
+
+# Install
+
+```bash
+$ npm install --save @commercetools-frontend/sdk
+```
+
+# Declarative Fetching
+
+There are two sides to declarative fetching:
+
+- describing the data we need to fetch declaratively
+- fetching by rendering a component instead of triggering the fetch imperatively
+
+This module aims to provide the necessary parts for both.
+
+## Declaring the fetch using a component
+
+> **⚠️ Deprecated** This component will likely not get developed any further. Use regular redux-style action creators for now. In the future we plan to use Apollo to replace this completely.
+
+The provided `Sdk.Get` component can be rendered to fetch data. It uses the
+middleware behind the scenes but adds some features on top. See
+[components/sdk-fetch/README.md](./components/sdk-fetch/README.md) for details.
+
+## Describing data declaratively
+
+The provided middleware takes an object which describes what data should be
+fetched. The middleware transforms that description into a promise and resolves
+the promise. It passes the response back to the callee.
+
+# Usage
+
+The middleware is a thin wrapper around [`sdk-client`](https://commercetools.github.io/nodejs/sdk/api/sdkClient.html). It offers a way to declaratively describe the data requirements.
+
+A Redux action using one of the action creators below needs to be dispatched. It contains the description of what to get/post/delete. The `sdk` middleware then turns the declarative description into imperative API calls on `sdk-client`. The dispatched action resolves with the result of `sdk-client`.
+
+## Action creators
+
+The action creators can be imported as
+
+```js
+import { actions as sdkActions } from '@commercetools-frontend/sdk';
+```
+
+### Methods
+
+The supported action creators are:
+
+- `sdkActions.get(config)`: sends a HTTP `GET`
+- `sdkActions.post(config)`: sends a HTTP `POST`
+- `sdkActions.del(config)`: sends a HTTP `DELETE`
+- `sdkActions.head(config)`: sends a HTTP `HEAD`
+
+### Specifying an endpoint
+
+There are two ways to describe an endpoint:
+
+- by `uri`: pass the URI as string
+- by `service`: uses the `@commercetools/api-request-builder` to build the URI. You can pass `config.options` to supply the necessary request parameters
+
+The `post` action creator additionally requires a `config.payload` object or string, containing the request payload.
+
+> The `mcApiProxyTarget` values are exposed from the `@commercetools-frontend/constants` package, as `MC_API_PROXY_TARGETS`. The value will be used to build a prefix to the `uri` as `/proxy/<mcApiProxyTarget>/<uri>`.
+
+**Usage with `uri`**
+
+```js
+{
+  uri: String,
+  mcApiProxyTarget?: ApiProxyTarget,
+  payload?: Object | String
+}
+```
+
+- `uri` can be relative or absolute. It gets passed to [`sdk-client`](https://commercetools.github.io/nodejs/sdk/api/sdkClient.html) as-is
+
+This approach must be used when querying something other than the CTP API. In case the CTP API is queried it is recommended to use `service` and `options` since that is easier to test. It is totally valid to provide `uri` only as well though.
+
+When both, `uri` and `options` (or `service`) are present, the `uri` takes precedence.
+
+**Usage with `service` and `options`**
+
+```js
+{
+  service: String,
+  options: Object,
+  mcApiProxyTarget?: ApiProxyTarget,
+  payload?: Object | String
+}
+```
+
+Before using the `sdk-client` the `sdk` middleware combines `service` and `options` using `api-request-builder`'s `parse` method to form a `uri`. It then makes the exact same request as when specifying `uri` directly.
+
+The supported `options` can be found in the `api-request-builder`'s documentation under the [Declarative Usage](https://commercetools.github.io/nodejs/sdk/api/apiRequestBuilder.html#declarative-usage) section.
+
+## Action creators for external API usage
+
+By default, all requests with the SDK are configured to be sent to the MC API.
+However, Custom Applications using the [Proxy to external API](https://docs.commercetools.com/merchant-center-customizations/concepts/integrate-with-your-own-api) need to configure the request a bit differently, and send additional headers.
+
+To make it easier to make requests to the proxy endpoint using the SDK, there is a new action creator wrapper that comes with built-in configuration options.
+
+The exported action creators have a new export `forwardTo`, which is an object containing wrappers around the normal action creators.
+
+```js
+actions.forwardTo.get(options);
+actions.forwardTo.del(options);
+actions.forwardTo.head(options);
+actions.forwardTo.post(options);
+```
+
+The options for the action creators are the same as the **Usage with `uri`**, except that the `uri` value needs to be the URL to the external API (see `X-Forward-To` header).
+
+The `forwardTo` action creators additionally set the following headers:
+
+- `Accept-version`
+- `X-Forward-To`
+- `X-Forward-To-Audience-Policy`
+
+For more information, check the [Proxy to external API](https://docs.commercetools.com/merchant-center-customizations/concepts/integrate-with-your-own-api) documentation.
+
+## Error handling
+
+Failed requests will result in a rejected promise. The `sdk-client`'s error handling applies, so network errors and CTP API errors on the content itself result in a rejected promise.
+
+The `sdk` package does not provide any error handling out of the box. It's the application's responsibility to handle errors (e.g. show a notification, track the error).
+
+The Merchant Center has a `handleActionError` function which is what we currently use for error handling. It logs the error to the tracking tool (Sentry) and shows a notification to the client. This should be used whenever a more special error handling is not necessary.
+
+## Example
+
+```js
+import { actions as sdkActions } from '@commercetools-frontend/sdk';
+
+const fetchProductById = (productId) =>
+  sdkActions.get({
+    service: 'products',
+    options: { id: productId },
+  });
+```
+
+```js
+import * as globalActions from '@commercetools-frontend/actions-global';
+
+class ProductPage extends React.Component {
+  state = { product: null };
+  componentDidMount() {
+    this.props.fetchProductById(this.props.productId).then(
+      (product) => {
+        this.setState({ product });
+      },
+      (error) => {
+        this.props.onActionError(error, 'ProductPage/fetchProductById');
+      }
+    );
+  }
+  render() {
+    if (!this.state.product) return <LoadingSpinner />;
+
+    return <div>{JSON.stringify(this.state.product)}</div>;
+  }
+}
+
+// and finally we need to pass the bound action creator to the component using plain old redux
+export default connect(null, {
+  fetchProductById: productsActions.fetchProductById,
+  onActionError: globalActions.handleActionError,
+})(ProductPage);
+```

package/dist/commercetools-frontend-sdk.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29tbWVyY2V0b29scy1mcm9udGVuZC1zZGsuY2pzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuL2RlY2xhcmF0aW9ucy9zcmMvaW5kZXguZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSJ9