@merchi/sdk 1.40.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Merchi
+
+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,244 @@
+# Merchi TypeScript SDK
+
+A TypeScript SDK for interacting with the Merchi API.
+
+[![npm version](https://img.shields.io/npm/v/@merchi/sdk.svg)](https://www.npmjs.com/package/@merchi/sdk)
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Authentication](#authentication)
+- [Basic Usage](#basic-usage)
+  - [Entity Operations](#entity-operations)
+  - [Embedding Related Entities](#embedding-related-entities)
+- [Available Entities](#available-entities)
+- [Examples](#examples)
+- [TypeScript Support](#typescript-support)
+- [License](#license)
+
+## Installation
+
+```bash
+# Using npm
+npm install @merchi/sdk
+
+# Using yarn
+yarn add @merchi/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Merchi, Product } from '@merchi/sdk';
+
+// 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**
+
+```typescript
+import { Merchi } from '@merchi/sdk';
+
+// 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:
+
+```typescript
+// 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:
+
+```typescript
+// 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:
+
+```typescript
+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
+
+```typescript
+import { Merchi, Product } from '@merchi/sdk';
+
+// 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
+
+```typescript
+import { Merchi, Cart, CartItem } from '@merchi/sdk';
+
+// 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.
+
+```typescript
+import { Product, EmbedDescriptor } from '@merchi/sdk';
+
+// 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](LICENSE) file for details.