npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@shopware/api-client

v1.2.0

Published

Shopware client for API connection.

Downloads

22,763

Readme

shopware/frontends - api-client

Dynamic and fully typed API Client for Shopware 6. Usable in any JavaScript and TypeScript project. You can use types generated from your custom API instance to have autocompletion and type safety.

To generate your own types use @shopware/api-gen CLI.

To take a deep dive into the topic visit the 🧑‍🎓 API Client Tutorial first.

Setup

Install npm package:

# ✨ Auto-detect
npx nypm install @shopware/api-client

# npm
npm install @shopware/api-client

# yarn
yarn add @shopware/api-client

# pnpm
pnpm install @shopware/api-client

# bun
bun install @shopware/api-client

Store API client setup

Recommended practice is to create a separate module file. For example src/apiClient.ts, and import it whenever you need to use API Client.

import { createAPIClient } from "@shopware/api-client";

// You can pick types of your current API version, the default one:
import type { operations } from "@shopware/api-client/store-api-types";
// or - RECOMMENDED - your types generated by [@shopware/api-gen](https://www.npmjs.com/package/@shopware/api-gen) CLI:
import type { operations } from "./api-types/storeApiTypes";

// you can pick cookies library of your choice
import Cookies from "js-cookie";

export const apiClient = createAPIClient<operations>({
  baseURL: "https://demo-frontends.shopware.store/store-api",
  accessToken: "SWSCBHFSNTVMAWNZDNFKSHLAYW",
  contextToken: Cookies.get("sw-context-token"),
});

apiClient.hook("onContextChanged", (newContextToken) => {
  Cookies.set("sw-context-token", newContextToken, {
    expires: 365, // days
    path: "/",
    sameSite: "lax",
    secure: shopwareEndpoint.startsWith("https://"),
  });
});

Admin API client setup

import { createAdminAPIClient } from "@shopware/api-client";

The setup works the same way as creteAPIClient function, with few differences

credentials (optional) - Quick scripting or token-based authentication

We provide optional credentials parameter to createAdminAPIClient. Which allows you to use authentication type of your choice whenever you wish to create connection to any endpoint.

Example:

import type {
  operations,
} from "@shopware/api-client/admin-api-types"; // we take default admin api types from different directory than store-api - use your own types by generating schema with @shopware/api-gen CLI
import type { operations } from "./api-types/adminApiTypes"; // or use your own types generated by @shopware/api-gen CLI

const adminApiClient = createAdminAPIClient<operations>({
  baseURL: `${process.env.SHOP_URL}/api`,
  credentials: {
    grant_type: "password",
    client_id: "administration",
    scopes: "write",
    username: process.env.SHOP_ADMIN_USERNAME,
    password: process.env.SHOP_ADMIN_PASSWORD,
  },
  // credentials: { // or token-based example
  //   grant_type: "client_credentials",
  //   client_id: "administration",
  //   client_secret: process.env.SHOP_ADMIN_TOKEN,
  // },
});

await adminApiClient.invoke(...); // invoke defined endpoint

sessionData (optional) - Persistent authentication

This parameter is used to store session data in cookies (or other place you want to store it), so you can keep your session persistent.

You can combine this option with credentials property.

// example adminApiClient.ts file
import { createAdminAPIClient } from "@shopware/api-client"; // we use different function to create admin api client

import { createAdminAPIClient } from "@shopware/api-client";
import type { operations, Schemas } from "@shopware/api-client/admin-api-types"; // we take default admin api types from different directory than store-api
import Cookies from "js-cookie";

export const adminApiClient = createAdminAPIClient<operations>({
  baseURL: "https://demo-frontends.shopware.store/api",
  sessionData: JSON.parse(Cookies.get("sw-admin-session-data") || "{}"),
});

adminApiClient.hooks("onAuthChange", (sessionData) => {
  Cookies.set("sw-admin-session-data", JSON.stringify(sessionData), {
    expires: 1, // days
    path: "/",
    sameSite: "lax",
    secure: shopwareEndpoint.startsWith("https://"),
  });
});

the rest works the same as store-api client.

Basic usage

Take a look at example project using API Client.

Simple invocation

import { apiClient, RequestReturnType } from "./apiClient";

// could be reactive value, you can use ApiReturnType to type it properly
let productsResponse: RequestReturnType<"readProduct">;

async function loadProducts() {
  productsResponse = await apiClient.invoke("readProduct post /product", {
    limit: 2,
  });
}

Fetch features

The new API client is leveraging ofetch library, which has built in support for AbortController, timeout and other features.

Example usage of AbortController to cancell your request:

const controller = new AbortController();

const request = client.invoke("readContext get /context", {
  fetchOptions: {
    signal: controller.signal,
  },
});

controller.abort(); // At this point client will throw an error with the information, that the request has been cancelled

Other example of using fetchOptions for setting the timeout:

const request = client.invoke("readContext get /context", {
  fetchOptions: {
    timeout: 5000, // 5 seconds
  },
});

All exposed options available under fetchOptions are:

  • cache
  • duplex
  • keepalive
  • priority
  • redirect
  • retry
  • retryDelay
  • retryStatusCodes
  • signal
  • timeout

Predefining methods

If you prefer to add another layer of abstraction you can use created previously types to define your own concept of methods.

// add for example into apiClient.ts file
const readNavigation = ({
  depth,
  type,
}: {
  depth: number;
  type: "main-navigation";
}) =>
  apiClient.invoke("readNavigation post /navigation/{activeId}/{rootId}", {
    headers: {
      "sw-include-seo-urls": true,
    },
    pathParams: {
      activeId: type,
      rootId: type,
    },
    body: {
      depth,
    },
  });

// in another file you can use it, and depth property will be set to 2 by default
import { readNavigation } from "./apiClient";

async function loadMainNavigation() {
  const navigation = await readNavigation({
    body: { activeId: "main-navigation", rootId: "main-navigation" },
  });
}

Error handling

Client is throwing ApiClientError with detailed information returned from the API. It will display clear message in the console or you can access details property to get raw information from the response.

import { ApiClientError } from "@shopware/api-client";

try {
  // ... your request
} catch (error) {
  if (error instanceof ApiClientError) {
    console.error(error); // This prints message summary
    console.error("Details:", error.details); // Raw response from API
  } else {
    console.error("==>", error); // Another type of error, not recognized by API client
  }
}

Hooks

Api client provides hooks to listen to events like context change, authentication change or default headers change. Example:

apiClient.hook("onDefaultHeaderChanged", (key, value) => {
  // here we can detect that the default header has changed, either by the user or by the headers incoming from the API
});

calling apiClient.hook will autocomplete the list of available hooks.

Links

Changelog

Full changelog for stable version is available here

Latest changes: 1.2.0

Minor Changes

  • #1468 a87bbcf Thanks @JimTacobs! - Added fetchOptions to both API clients to allow for base configuration of http client