Merchi TypeScript SDK

A TypeScript SDK for interacting with the Merchi API.

Table of Contents

• Installation
• Quick Start
• Configuration
• Authentication
• Basic Usage
  • Entity Operations
  • Embedding Related Entities
• Available Entities
• Examples
• TypeScript Support
• License

Installation

# Using npm
npm install merchi_sdk_ts

# Using yarn
yarn add merchi_sdk_ts

Quick Start

import { Merchi, Product } from 'merchi_sdk_ts';

// Initialize the SDK
const merchi = new Merchi();

// Fetch a product by ID
Product.get(123).then(product => {
  console.log(product.name);
});

Configuration

The SDK by default is set up to make requests to the Merchi production server at https://api.merchi.co/v6/.

You can customize the API endpoint by:

1. Setting process.env.MERCHI_BACKEND_URI in your Node.js environment.
2. Setting window.merchiBackendUri in the browser.
3. Passing the backendUri directly to the Merchi constructor (highest precedence).

The SDK will look for these in the order of 3, 2, 1, and finally use the default production URL if none are found. The API version (e.g., /v6/) will be appended automatically if not included in your custom URI, assuming the URI ends with the base domain (e.g. https://custom.merchi.co). If your custom URI already includes a path (e.g., https://custom.merchi.co/api/), ensure it ends with a trailing slash for the version to be appended correctly (e.g., https://custom.merchi.co/api/v6/).

Example: Passing backendUri to the constructor

import { Merchi } from 'merchi_sdk_ts';

// Initialize the SDK with a custom backend URI
// This URI should be the base path to your Merchi backend instance.
// The API version (e.g., /v6/) will be appended.
const customBackend = 'https://my-custom-merchi-instance.com/';
const merchi = new Merchi(undefined, undefined, undefined, undefined, customBackend);

// If your custom URI already includes a specific path and you want to control the full endpoint:
const specificCustomBackend = 'https://my-custom-merchi-instance.com/api/custom_version/';
const merchiSpecific = new Merchi(undefined, undefined, undefined, undefined, specificCustomBackend);

// Now, all API calls made using this 'merchi' or 'merchiSpecific' instance
// will be directed to your specified backend.
// For example:
// merchi.Product.get(1) will call https://my-custom-merchi-instance.com/v6/products/1/
// merchiSpecific.Product.get(1) will call https://my-custom-merchi-instance.com/api/custom_version/products/1/

Authentication

The SDK supports several authentication methods:

// Session token authentication (most common)
const merchi = new Merchi('your-session-token');

// Alternative methods
const merchi = new Merchi(
  'your-session-token',     // Session token
  'your-client-token',      // Client token
  'your-invoice-token',     // Invoice token
  'your-cart-token'         // Cart token
);

// The SDK will also attempt to read session_token from cookies
// if no token is provided

Basic Usage

Entity Operations

Each entity supports standard CRUD operations:

// Fetch a single entity
Product.get(123).then(product => {
  console.log(product);
});

// List entities with filtering
Product.list({
  limit: 10,
  offset: 0,
  q: 'search-term'
}).then(response => {
  console.log(response.items);        // Array of products
  console.log(response.metadata);     // Metadata including count, limit, offset
});

// Create a new entity
const product = new Product();
product.name = 'New Product';
product.description = 'Product description';
product.create().then(newProduct => {
  console.log(newProduct.id);
});

// Update an entity
product.name = 'Updated Product Name';
product.save().then(updatedProduct => {
  console.log(updatedProduct);
});

// Delete an entity
product.delete().then(() => {
  console.log('Product deleted');
});

Embedding Related Entities

You can request related entities be included in responses:

Product.get(123, {
  embed: {
    domain: {},
    variations: {
      variationFields: {}
    }
  }
}).then(product => {
  console.log(product.domain);            // Domain entity is included
  console.log(product.variations);        // Variations are included
  console.log(product.variations[0].variationFields);  // Fields are included
});

Available Entities

The SDK provides access to all Merchi entities, including but not limited to:

• User, Company, Domain
• Product, Category, Variation
• Cart, CartItem
• Job, Assignment, Invoice
• File, Draft, DraftTemplate
• Payment, Shipment
• And many more...

Each entity maps directly to the corresponding API endpoint and data structure.

Examples

Working with Products

import { Merchi, Product } from 'merchi_sdk_ts';

// Initialize Merchi
const merchi = new Merchi('your-session-token');

// Create a new product
const product = new Product();
product.name = 'Custom T-Shirt';
product.description = 'High-quality custom printed t-shirt';
product.public = true;

product.create().then(newProduct => {
  console.log(`Created product with ID: ${newProduct.id}`);
});

Managing a Cart

import { Merchi, Cart, CartItem } from 'merchi_sdk_ts';

// Initialize Merchi
const merchi = new Merchi('your-session-token');

// Create a new cart
const cart = new Cart();
cart.create().then(newCart => {
  // Add an item to the cart
  const cartItem = new CartItem();
  cartItem.productId = 123;
  cartItem.quantity = 2;
  cartItem.cartId = newCart.id;
  
  return cartItem.create();
}).then(newCartItem => {
  console.log('Item added to cart!');
});

TypeScript Support

This SDK is built with TypeScript and provides full type definitions for all entities and operations.

import { Product, EmbedDescriptor } from 'merchi_sdk_ts';

// TypeScript will provide intellisense for all properties
const product = new Product();
product.name = 'New Product';

// Type checking for embed options
const embedOptions: EmbedDescriptor = {
  domain: {},
  variations: {
    variationFields: {}
  }
};

Product.get(123, { embed: embedOptions });

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.