Malonlin SDK Docs
Docs / Getting Started

Install and connect

The SDK is designed to feel at home in a Node.js service, a browser app, or another JavaScript runtime with fetch. It has no React dependency.

Install the package#

Install the SDK from npm in your app's folder:

sh
npm install malonlin-sdk

Once installation is complete, set up the marketplace account and API key. Then follow the first store walkthrough to create a working store and draft product.

Create a client#

ts
import { CartSDK } from 'malonlin-sdk';

const sdk = new CartSDK({
  endpoint: 'https://your-api.example/graphql',
  accessToken: 'user-access-token',
});

The SDK sends GraphQL requests to the endpoint you configure. In this workspace, malonlin-n is the server paired with SDK development; the React website is served by malonlin-website-v1. Point an integration at the deployed server intended for that integration, and make sure its API-key, authentication, CORS, and environment settings allow the request. The SDK does not start or host a backend.

If users sign in after the SDK is created, update the token without rebuilding the client:

ts
sdk.setAccessToken('new-access-token');

For applications that refresh tokens in the background, pass a callback instead:

ts
const sdk = new CartSDK({
  endpoint: 'https://your-api.example/graphql',
  getAccessToken: () => authSession.getAccessToken(),
});

API keys and browser apps#

The Malonlin backend may require an API key. You can provide one with apiKey for trusted server-side use. Do not put a private API key in a browser bundle: browser code is visible to visitors. For browser integrations, use a server-side proxy or a deliberately restricted public key configured by the backend operator.

You may pass a custom fetch, request headers, CSRF token provider, and timeout in the client options. See the API reference, Feature clients, and the full Input, field, and event reference for required/optional fields, SDK events, webhook payloads, and subscriber signature headers.

ts
const sdk = new CartSDK({
  endpoint: process.env.MALONLIN_GRAPHQL_ENDPOINT!,
  getAccessToken: () => authSession.getAccessToken(),
  csrfToken: () => authSession.getCsrfToken(),
  timeoutMs: 15_000,
});

Only provide a non-null CSRF token when your backend's browser/session policy requires one. Never place private environment variables in a client-side bundle.

Upload product and profile media#

The website also uploads media through a multipart HTTP endpoint rather than GraphQL. By default, the SDK derives /upload from the configured GraphQL path; if your deployment uses a different route on the same origin, set uploadEndpoint explicitly:

ts
const sdk = new CartSDK({
  endpoint: 'https://api.example/graphql',
  uploadEndpoint: 'https://api.example/api/upload',
  getAccessToken: () => authSession.getAccessToken(),
});

const uploaded = await sdk.uploads.upload(file, {
  folder: 'products',
  publicRead: true,
  fileName: file.name,
});

The upload endpoint must share the GraphQL endpoint's origin so credentials are never forwarded to another host. The upload response must include key and url. Keep privileged API keys on a trusted server; browser code should use an appropriately restricted public key or a server-side proxy.

Malonlin SDK documentation