merchi_sdk_ts 1.0.70 → 1.0.72-test

package/README.md

@@ -1,22 +1,244 @@
-# merchi_cart
-Merchi's cart
+# Merchi TypeScript SDK
 
+A TypeScript SDK for interacting with the Merchi API.
+
+[![npm version](https://img.shields.io/npm/v/merchi_sdk_ts.svg)](https://www.npmjs.com/package/merchi_sdk_ts)
+[![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)
-- [Usage](#usage)
+- [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_ts
 
-or
-
+# Using yarn
 yarn add merchi_sdk_ts
 ```
 
-### Usage
-  The sdk by default is set up to make request to the Merchi production server 'https://api.merchi.co/'.
-  You can set the API URI by setting `process.env.MERCHI_BACKEND_URI` in your environment or `window.merchiBackendUri` on the client.
+## Quick Start
+
+```typescript
+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**
+
+```typescript
+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:
+
+```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_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
+
+```typescript
+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.
+
+```typescript
+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](LICENSE) file for details.

package/dist/entities/cart_item.js

@@ -116,6 +116,10 @@ var CartItem = /** @class */ (function (_super) {
         CartItem.property({ arrayType: 'DomainTag' }),
         __metadata("design:type", Array)
     ], CartItem.prototype, "tags", void 0);
+    __decorate([
+        CartItem.property({ arrayType: 'Draft' }),
+        __metadata("design:type", Array)
+    ], CartItem.prototype, "ownDrafts", void 0);
     return CartItem;
 }(Entity));
 export { CartItem };

package/dist/merchi.js

@@ -91,8 +91,9 @@ function cloneClass(original, arg) {
     Object.assign(copy, original);
     return copy;
 }
+export var API_VERSION = 'v6';
 var Merchi = /** @class */ (function () {
-    function Merchi(sessionToken, clientToken, invoiceToken, cartToken) {
+    function Merchi(sessionToken, clientToken, invoiceToken, cartToken, backendUri) {
         var _this = this;
         this.id = generateUUID();
         this.authenticatedFetch = function (resource, options, expectEmptyResponse) {
@@ -116,7 +117,8 @@ var Merchi = /** @class */ (function () {
                 /* istanbul ignore next */
                 options.query.push(['cart_token', _this.cartToken]);
             }
-            return apiFetch(resource, options, expectEmptyResponse);
+            // Pass the full backendUri, and resource is now just the endpoint
+            return apiFetch(_this.backendUri, resource, options, expectEmptyResponse);
         };
         /* istanbul ignore next */
         this.authenticatedFetchWithProgress = function (resource, options, progressCallback) {
@@ -135,7 +137,8 @@ var Merchi = /** @class */ (function () {
             if (_this.cartToken) {
                 options.query.push(['cart_token', _this.cartToken]);
             }
-            return apiFetchWithProgress(resource, options, progressCallback);
+            // Pass the full backendUri, and resource is now just the endpoint
+            return apiFetchWithProgress(_this.backendUri, resource, options, progressCallback);
         };
         this.getCurrentUser = function (options) {
             var _a = (options || {}).embed, embed = _a === void 0 ? {} : _a;
@@ -171,6 +174,30 @@ var Merchi = /** @class */ (function () {
         else {
             this.cartToken = getCookie('cart_token');
         }
+        var determinedBaseUri = backendUri;
+        if (!determinedBaseUri) {
+            var clientBackendUri = typeof window !== 'undefined' &&
+                window.merchiBackendUri ?
+                window.merchiBackendUri : undefined;
+            if (clientBackendUri) {
+                determinedBaseUri = clientBackendUri;
+            }
+        }
+        if (!determinedBaseUri) {
+            var envBackendUri = typeof process !== 'undefined' &&
+                process.env.MERCHI_BACKEND_URI ?
+                process.env.MERCHI_BACKEND_URI : undefined;
+            if (envBackendUri) {
+                determinedBaseUri = envBackendUri;
+            }
+        }
+        if (!determinedBaseUri) {
+            determinedBaseUri = 'https://api.merchi.co/';
+        }
+        if (!determinedBaseUri.endsWith('/')) {
+            determinedBaseUri += '/';
+        }
+        this.backendUri = determinedBaseUri + API_VERSION + '/';
         // re-export configured versions of all classes
         this.AutomaticPaymentRelationship = this.setupClass(AutomaticPaymentRelationship);
         this.Variation = this.setupClass(Variation);

package/dist/request.js

@@ -45,39 +45,28 @@ var ApiError = /** @class */ (function (_super) {
 }(Error));
 export { ApiError };
 export var version = 'v6';
-export function backendFetch(resource, options) {
+export function backendFetch(baseUrl, resource, options) {
     var e_1, _a;
-    var _b;
-    var defaultBackendUri = 'https://api.merchi.co/';
-    // backend uri as defined on the window element takes priority
-    var clientBackendUri = typeof window !== 'undefined' &&
-        window.merchiBackendUri ?
-        window.merchiBackendUri : undefined;
-    // backend uri as defined on env
-    var envBackendUri = typeof process !== 'undefined' &&
-        process.env.MERCHI_BACKEND_URI ?
-        process.env.MERCHI_BACKEND_URI : undefined;
-    var server = (_b = envBackendUri !== null && envBackendUri !== void 0 ? envBackendUri : clientBackendUri) !== null && _b !== void 0 ? _b : defaultBackendUri;
-    var url = new URL(server + version + resource);
+    var url = new URL(resource, baseUrl);
     if (options && options.query) {
         try {
-            for (var _c = __values(options.query), _d = _c.next(); !_d.done; _d = _c.next()) {
-                var entry = _d.value;
+            for (var _b = __values(options.query), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var entry = _c.value;
                 url.searchParams.append(entry[0], entry[1]);
             }
         }
         catch (e_1_1) { e_1 = { error: e_1_1 }; }
         finally {
             try {
-                if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
             }
             finally { if (e_1) throw e_1.error; }
         }
     }
     return fetch(url.toString(), options);
 }
-export function apiFetch(resource, options, expectEmptyResponse) {
-    return backendFetch(resource, options).then(function (response) {
+export function apiFetch(baseUrl, resource, options, expectEmptyResponse) {
+    return backendFetch(baseUrl, resource, options).then(function (response) {
         if (response.status < 200 || response.status > 299) {
             return response.json().then(function (json) {
                 var err = new ApiError(json);
@@ -90,8 +79,8 @@ export function apiFetch(resource, options, expectEmptyResponse) {
     });
 }
 /* istanbul ignore next */
-export function apiFetchWithProgress(resource, options, progressCallback) {
-    return backendFetch(resource, options).then(function (response) {
+export function apiFetchWithProgress(baseUrl, resource, options, progressCallback) {
+    return backendFetch(baseUrl, resource, options).then(function (response) {
         if (!response.body) {
             var err = new ApiError('empty response');
             return Promise.reject(err);

package/dist/request.test.js

@@ -4,20 +4,20 @@ import { setup, mockFetch } from './test_util.js';
 setup();
 test('can pass through data from server', function () {
     mockFetch(true, { 'animal': 'turtle' }, 200);
-    return apiFetch('/test').then(function (data) {
+    return apiFetch('https://api.merchi.co/', '/test').then(function (data) {
         expect(data.animal).toBe('turtle');
     });
 });
 test('can pass through data from server with override url', function () {
     window.merchiBackendUri = 'http://override.example.com/';
     mockFetch(true, { 'animal': 'turtle' }, 200);
-    return apiFetch('/test').then(function (data) {
+    return apiFetch('https://api.merchi.co/', '/test').then(function (data) {
         expect(data.animal).toBe('turtle');
     });
 });
 test('404 creates ApiError', function () {
     mockFetch(false, { 'statusCode': 404, 'errorCode': ErrorType.RESOURCE_NOT_FOUND }, 404);
-    apiFetch('/test').catch(function (e) {
+    apiFetch('https://api.merchi.co/', '/test').catch(function (e) {
         expect(e.statusCode).toBe(404);
         expect(e.name).toBe('ApiError');
         expect(e.errorCode).toBe(ErrorType.RESOURCE_NOT_FOUND);
@@ -28,7 +28,7 @@ test('will get default errorCode', function () {
     mockFetch(false, { 'statusCode': 404,
         'errorCode': -1,
         'message': 'just a test' }, 404);
-    apiFetch('/test').catch(function (e) {
+    apiFetch('https://api.merchi.co/', '/test').catch(function (e) {
         expect(e.statusCode).toBe(404);
         expect(e.name).toBe('ApiError');
         expect(e.errorCode).toBe(ErrorType.UNKNOWN_ERROR);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "merchi_sdk_ts",
-  "version": "1.0.70",
+  "version": "1.0.72-test",
   "main": "dist/index.js",
   "type": "module",
   "repository": "git@github.com:merchisdk/merchi_sdk_ts.git",

package/src/entities/cart_item.ts

@@ -6,6 +6,7 @@ import { RequestOptions } from '../request.js';
 import { Variation } from './variation.js';
 import { VariationsGroup } from './variations_group.js';
 import { DomainTag } from './domain_tag.js';
+import { Draft } from './draft.js';
 
 export class CartItem extends Entity {
   protected static resourceName = 'cart_items';
@@ -57,6 +58,9 @@ export class CartItem extends Entity {
   @CartItem.property({arrayType: 'DomainTag'})
   public tags?: DomainTag[];
 
+  @CartItem.property({arrayType: 'Draft'})
+  public ownDrafts?: Draft[];
+
   public requiresShipment = () => {
     if (this.product === undefined) {
       throw 'product is undefined, did you forget to embed it?';

package/src/merchi.ts

@@ -99,6 +99,8 @@ interface UserRequestOptions {
   embed?: EmbedDescriptor;
 }
 
+export const API_VERSION = 'v6';
+
 export class Merchi {
   public id: string = generateUUID();
 
@@ -106,6 +108,7 @@ export class Merchi {
   public invoiceToken?: string;
   public clientToken?: string;
   public cartToken?: string;
+  public readonly backendUri: string;
 
   public AutomaticPaymentRelationship: typeof AutomaticPaymentRelationship;
   public Notification: typeof Notification;
@@ -189,7 +192,8 @@ export class Merchi {
     sessionToken?: string,
     clientToken?: string,
     invoiceToken?: string,
-    cartToken?: string
+    cartToken?: string,
+    backendUri?: string
   ) {
     if (sessionToken) {
       this.sessionToken = sessionToken;
@@ -215,6 +219,32 @@ export class Merchi {
       this.cartToken = getCookie('cart_token');
     }
 
+    let determinedBaseUri = backendUri;
+    if (!determinedBaseUri) {
+      const clientBackendUri = typeof window !== 'undefined' &&
+        (window as any).merchiBackendUri ?
+        (window as any).merchiBackendUri : undefined;
+      if (clientBackendUri) {
+        determinedBaseUri = clientBackendUri;
+      }
+    }
+    if (!determinedBaseUri) {
+      const envBackendUri = typeof process !== 'undefined' &&
+        process.env.MERCHI_BACKEND_URI ?
+        process.env.MERCHI_BACKEND_URI : undefined;
+      if (envBackendUri) {
+        determinedBaseUri = envBackendUri;
+      }
+    }
+    if (!determinedBaseUri) {
+      determinedBaseUri = 'https://api.merchi.co/';
+    }
+
+    if (!determinedBaseUri.endsWith('/')) {
+      determinedBaseUri += '/';
+    }
+    this.backendUri = determinedBaseUri + API_VERSION + '/';
+
     // re-export configured versions of all classes
     this.AutomaticPaymentRelationship = this.setupClass(
       AutomaticPaymentRelationship
@@ -348,7 +378,8 @@ export class Merchi {
       /* istanbul ignore next */
       options.query.push(['cart_token', this.cartToken]);
     }
-    return apiFetch(resource, options, expectEmptyResponse);
+    // Pass the full backendUri, and resource is now just the endpoint
+    return apiFetch(this.backendUri, resource, options, expectEmptyResponse);
   };
 
   /* istanbul ignore next */
@@ -372,7 +403,8 @@ export class Merchi {
     if (this.cartToken) {
       options.query.push(['cart_token', this.cartToken]);
     }
-    return apiFetchWithProgress(resource, options, progressCallback);
+    // Pass the full backendUri, and resource is now just the endpoint
+    return apiFetchWithProgress(this.backendUri, resource, options, progressCallback);
   };
 
   public getCurrentUser = (options?: UserRequestOptions) => {

package/src/request.test.ts

@@ -6,7 +6,7 @@ setup();
 
 test('can pass through data from server', () => {
   mockFetch(true, {'animal': 'turtle'}, 200);
-  return apiFetch('/test').then(data => {
+  return apiFetch('https://api.merchi.co/', '/test').then(data => {
     expect(data.animal).toBe('turtle');
   });
 });
@@ -14,14 +14,14 @@ test('can pass through data from server', () => {
 test('can pass through data from server with override url', () => {
   (window as any).merchiBackendUri = 'http://override.example.com/';
   mockFetch(true, {'animal': 'turtle'}, 200);
-  return apiFetch('/test').then(data => {
+  return apiFetch('https://api.merchi.co/', '/test').then(data => {
     expect(data.animal).toBe('turtle');
   });
 });
 
 test('404 creates ApiError', () => {
   mockFetch(false, {'statusCode': 404, 'errorCode': ErrorType.RESOURCE_NOT_FOUND}, 404);
-  apiFetch('/test').catch(e => {
+  apiFetch('https://api.merchi.co/', '/test').catch(e => {
     expect(e.statusCode).toBe(404);
     expect(e.name).toBe('ApiError');
     expect(e.errorCode).toBe(ErrorType.RESOURCE_NOT_FOUND);
@@ -34,7 +34,7 @@ test('will get default errorCode', () => {
     {'statusCode': 404,
       'errorCode': -1,
       'message': 'just a test'}, 404);
-  apiFetch('/test').catch(e => {
+  apiFetch('https://api.merchi.co/', '/test').catch(e => {
     expect(e.statusCode).toBe(404);
     expect(e.name).toBe('ApiError');
     expect(e.errorCode).toBe(ErrorType.UNKNOWN_ERROR);

package/src/request.ts

@@ -25,18 +25,8 @@ export class ApiError extends Error {
 
 export const version = 'v6';
 
-export function backendFetch(resource: string, options?: RequestOptions) {
-  const defaultBackendUri: string = 'https://api.merchi.co/';
-  // backend uri as defined on the window element takes priority
-  const clientBackendUri = typeof window !== 'undefined' &&
-    (window as any).merchiBackendUri ?
-      (window as any).merchiBackendUri : undefined;
-  // backend uri as defined on env
-  const envBackendUri = typeof process !== 'undefined' &&
-    process.env.MERCHI_BACKEND_URI ?
-      process.env.MERCHI_BACKEND_URI : undefined;
-  const server = envBackendUri ?? clientBackendUri ?? defaultBackendUri;
-  const url = new URL(server + version + resource);
+export function backendFetch(baseUrl: string, resource: string, options?: RequestOptions) {
+  const url = new URL(resource, baseUrl);
   if (options && options.query) {
     for (const entry of options.query) {
       url.searchParams.append(entry[0], entry[1]);
@@ -46,11 +36,12 @@ export function backendFetch(resource: string, options?: RequestOptions) {
 }
 
 export function apiFetch(
+  baseUrl: string,
   resource: string,
   options?: RequestOptions,
   expectEmptyResponse?: boolean
 ) {
-  return backendFetch(resource, options as RequestInit | undefined).then(
+  return backendFetch(baseUrl, resource, options as RequestInit | undefined).then(
     function (response) {
       if (response.status < 200 || response.status > 299) {
         return response.json().then(function (json) {
@@ -66,11 +57,12 @@ export function apiFetch(
 
 /* istanbul ignore next */
 export function apiFetchWithProgress(
+  baseUrl: string,
   resource: string,
   options?: RequestOptions,
   progressCallback?: (progress: number) => void
 ) {
-  return backendFetch(resource, options as RequestInit | undefined).then(
+  return backendFetch(baseUrl, resource, options as RequestInit | undefined).then(
     function (response) {
       if (!response.body) {
         const err = new ApiError('empty response');