{% endopenapi %}
# API Client
Lightweight JS client for the Swish REST API.
The Swish API Client provides type-save methods for developers to interact with the API.
{% hint style="warning" %}
When integrating Swish into a browser environment, using the [Browser library](/libraries/browser) is recommended.
{% endhint %}
## Requirements
This packages works in all JS environments were the [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) is available.
## Installation
```sh
npm install @swishapp/api-client
```
## Usage
```typescript
import { createApiClient } from "@swishapp/api-client";
const swish = createApiClient({
authToken: "your-api-auth-token"
});
const { data } = await swish.items.list();
```
## Reference
### Items
{% hint style="success" %}
For more details, refer to the [Items API reference](/swish-api/api-reference/items).
{% endhint %}
#### List all items
```typescript
const { data, error } = await swish.items.list();
```
#### List all items (pagination)
```typescript
const { data, error } = await swish.items.list({
page: "page-cursor",
limit: 20,
});
```
#### List all items (search query)
```typescript
const { data, error } = await swish.items.list({
query: "product:123",
});
```
#### Create new item
```typescript
const { data, error } = await swish.items.create({
productId: 123, variantId: 456, quantity: 1,
});
```
#### Delete multiple items
const { error } = await swish.items.delete([
"item-id-1",
"item-id-2",
]);
#### Find item by ID
```typescript
const { data, error } = await swish.items.findById("item-id");
```
#### Update item by ID
```typescript
const { data, error } = await swish.items.updateById("item-id", {
variantId: 456,
});
```
#### Delete item by ID
```typescript
const { error } = await swish.items.deleteById("item-id");
```
### Lists
{% hint style="success" %}
For more details, refer to the [Lists API reference](/swish-api/api-reference/lists).
{% endhint %}
#### List all lists
```typescript
const { data, error } = await swish.lists.list();
```
#### Create new list
```typescript
const { data, error } = await swish.lists.create({
name: "Favourites",
});
```
#### Find list by ID
```typescript
const { data, error } = await swish.lists.findById("list-id");
```
#### Find list by ID (items sorted in custom order)
```typescript
const { data, error } = await swish.lists.findById("list-id", {
sort: "customer"
});
```
#### Update list by ID
```typescript
const { data, error } = await swish.lists.updateById("list-id", {
name: "New list name",
});
```
#### Delete list by ID
```typescript
const { error } = await swish.lists.deleteById("list-id");
```
#### Set custom item order
```typescript
const { data, error } = await swish.lists.orderItems("list-id", {
itemIds: ["item-id-2", "item-id-1"],
});
```
### Profiles
{% hint style="success" %}
For more details, refer to the [Profiles API reference](/swish-api/api-reference/profiles).
{% endhint %}
#### Create new token
```typescript
const { data, error } = await swish.profiles.createToken({
customer: "gid://shopify/Customer/1234567",
})
```
# Browser
JS library to integrate Swish into a browser environment.
JavaScript library for integrating Swish on a Shopify web store (themes and headless stacks).
## Requirements
This library depends on the following browser APIs.
* [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
* [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)
* [Web Workers API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)
### Swish App Proxy
The Swish browser library requires a proxy service that operates on the same domain as the store. This service facilitates the loading of additional resources and ensures secure communication with the Swish API. The app proxy is automatically provided once the app has been installed.
If your store has it's own server (e.g. headless stack), then you will need to implement the proxy first. Please use the [Node.js library](/libraries/node.js) to implement the app proxy.
## Installation
To load the Swish app, you can either activate the Swish embed through your theme editor or install it via NPM. We recommend using the app embed for most scenarios. For headless stacks, NPM is necessary.
## Usage
```typescript
import { swishApp } from "/apps/wishlist/assets/swish.js";
const swish = await swishApp({
proxy: {
baseUrl: "/apps/wishlist"
}
});
const { data } = await swish.api.items.list();
```
### Reference
#### Swish API
All Swish API functions can be accessed and are automatically scoped to the current user.
```typescript
const { data } = await swish.api.items.list();
```
{% hint style="success" %}
Please refer to the [Swish API Client](/libraries/api-client) docs for a comprehensive list of available functions.
{% endhint %}
#### Swish UI Components
{% hint style="danger" %}
This feature is still under development!
{% endhint %}
To accelerate development, consider using our built-in UI components. These components follow a general design language and allow for some customisation. For a completely tailored user experience, creating your own UI components is recommended.
Our components load only when needed, enabling you to blend custom UI elements with our standard components without impacting your page speed.
await swish.ui.showSignIn({
returnTo: window.location.pathname
});
# Node.js
JS library to integrate Swish on a Node.js server.
## Swish app proxy for Node.js
The Swish browser library requires a proxy service that operates on the same domain as the store. This service facilitates the loading of additional resources and ensures secure communication with the Swish API.
### Installation
```sh
npm i @swishapp/node
```
### Usage
The example below is for Remix and needs to be adjusted for other frameworks.
```js
import { ActionFunction, LoaderFunction } from "@remix-run/node";
import { createProxy, MemoryStorage } from "@swishapp/node";
const swishProxy = createProxy({
basePath: "/swish", // Needs to match the route path
authToken: process.env.SWISH_API_TOKEN,
storage: new MemoryStorage(), // Use MemoryStorage for development only!
authenticate: async (request) => {
// Authenticate the request and return customer id or null
// Throw an error if the request cannot be authenticted
return null;
},
onError: (error) => {
console.error(error);
},
});
export const loader: LoaderFunction = async ({ request }) =>
swishProxy.forward(request);
export const action: ActionFunction = async ({ request }) =>
swishProxy.forward(request);
```
The Swish app for browsers won't work on the server. Use it as a client only script!
```ts
// The proxy also serves the Swish brwoser app
import { createApp } from "/swish/assets/swish.js"; // Assuming the proxy runs on /swish
const swish = await createApp({
proxy: {
baseUrl: "/swish", // Use proxy route path
},
});
```
# React
JS library to integrate Swish into a React project.
{% hint style="danger" %}
The REACT library is coming soon!
{% endhint %}
## Requirements
This package requires React 18 or newer.