@merchi/sdk 1.40.2

package/src/entities/product_review.ts

@@ -0,0 +1,221 @@
+import { Entity } from '../entity.js';
+import type { RequestOptions } from '../request.js';
+import type { Domain } from './domain.js';
+import type { Job } from './job.js';
+import type { Product } from './product.js';
+
+/** Create payload; the API expects ``jobId`` — pass ``job`` with at least ``id``. */
+export interface ProductReviewCreateInput {
+  job: { id: number };
+  rating: number;
+  title?: string | null;
+  content?: string | null;
+}
+
+export interface ProductReviewPatchInput {
+  status?: string;
+  rejectionReason?: string | null;
+  rating?: number;
+  title?: string | null;
+  content?: string | null;
+}
+
+/**
+ * Post-purchase product review. List/create are nested under ``/products/:id/reviews/``;
+ * updates use ``/product-reviews/:id/``. Do not use :meth:`Entity.create` / :meth:`Entity.list`
+ * for this resource.
+ *
+ * API responses use ``jobId``, ``productId``, and ``domainId``; this entity maps those onto
+ * ``job``, ``product``, and ``domain`` (minimal ``{ id }`` objects unless the API nests more).
+ */
+export class ProductReview extends Entity {
+  protected static resourceName = 'product-reviews';
+  protected static singularName = 'productReview';
+  protected static pluralName = 'productReviews';
+
+  @ProductReview.property()
+  public id?: number;
+
+  @ProductReview.property({ type: 'Product' })
+  public product?: Product;
+
+  @ProductReview.property({ type: 'Domain' })
+  public domain?: Domain;
+
+  @ProductReview.property({ type: Number })
+  public authorUserId?: number;
+
+  @ProductReview.property({ type: String })
+  public authorName?: string | null;
+
+  @ProductReview.property({ type: 'Job' })
+  public job?: Job;
+
+  @ProductReview.property({ type: Number })
+  public rating?: number;
+
+  @ProductReview.property({ type: String })
+  public title?: string | null;
+
+  @ProductReview.property({ type: String })
+  public content?: string | null;
+
+  @ProductReview.property({ type: String })
+  public status?: string;
+
+  @ProductReview.property({ type: Number })
+  public purchaseInvoiceId?: number | null;
+
+  /** ISO 8601 string from the API. */
+  @ProductReview.property({ type: String })
+  public submittedAt?: string | null;
+
+  /** ISO 8601 string from the API. */
+  @ProductReview.property({ type: String })
+  public updatedAt?: string | null;
+
+  @ProductReview.property({ type: String })
+  public rejectionReason?: string | null;
+
+  /**
+   * Map flat API fields (``jobId``, ``productId``, ``domainId``) to nested
+   * ``job`` / ``product`` / ``domain`` objects before :meth:`Entity.fromJson`.
+   */
+  public static normalizeApiJson(json: any): any {
+    if (json === null || json === undefined || typeof json !== 'object') {
+      return json;
+    }
+    const row: any = { ...json };
+    if (row.jobId !== undefined && row.job === undefined) {
+      if (row.jobId != null) {
+        row.job = { id: row.jobId };
+      }
+      delete row.jobId;
+    }
+    if (row.productId !== undefined && row.product === undefined) {
+      if (row.productId != null) {
+        row.product = { id: row.productId };
+      }
+      delete row.productId;
+    }
+    if (row.domainId !== undefined && row.domain === undefined) {
+      if (row.domainId != null) {
+        row.domain = { id: row.domainId };
+      }
+      delete row.domainId;
+    }
+    return row;
+  }
+
+  /**
+   * Domain managers/admins: list reviews for a product.
+   */
+  public static listForProduct(
+    this: typeof ProductReview,
+    productId: number,
+    options?: { withRights?: boolean }
+  ): Promise<ProductReview[]> {
+    const Constructor = this;
+    const resource = `/products/${productId}/reviews/`;
+    const fetchOptions: RequestOptions = { method: 'GET' };
+    fetchOptions.query = [];
+    if (!(options && options.withRights)) {
+      fetchOptions.query.push(['skip_rights', 'y']);
+    }
+    return Constructor.merchi.authenticatedFetch(resource, fetchOptions).then(
+      (data: any) => {
+        const raw = data.productReviews ?? [];
+        return raw.map((row: any) => {
+          const e: ProductReview = new Constructor() as ProductReview;
+          e.fromJson(ProductReview.normalizeApiJson(row));
+          return e;
+        });
+      }
+    );
+  }
+
+  /**
+   * Buyer: create a review for the catalog ``productId`` (master product).
+   * ``body.job.id`` must be a completed job whose line item resolves to this product.
+   */
+  public static createForProduct(
+    this: typeof ProductReview,
+    productId: number,
+    body: ProductReviewCreateInput,
+    options?: { withRights?: boolean }
+  ): Promise<ProductReview> {
+    const Constructor = this;
+    const resource = `/products/${productId}/reviews/`;
+    const wire: Record<string, unknown> = {
+      jobId: body.job.id,
+      rating: body.rating,
+    };
+    if (body.title !== undefined) {
+      wire.title = body.title;
+    }
+    if (body.content !== undefined) {
+      wire.content = body.content;
+    }
+    const fetchOptions: RequestOptions = {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(wire),
+    };
+    fetchOptions.query = [];
+    if (!(options && options.withRights)) {
+      fetchOptions.query.push(['skip_rights', 'y']);
+    }
+    return Constructor.merchi.authenticatedFetch(resource, fetchOptions).then(
+      (data: any) => {
+        const e: ProductReview = new Constructor() as ProductReview;
+        e.fromJson(ProductReview.normalizeApiJson(data.productReview));
+        return e;
+      }
+    );
+  }
+
+  /**
+   * Partial update (moderation or author edit). Uses ``multipart/form-data`` fields
+   * matching the Merchi API.
+   */
+  public patch(
+    payload: ProductReviewPatchInput,
+    options?: { withRights?: boolean }
+  ): Promise<this> {
+    const id = this.id;
+    if (id === undefined) {
+      throw new Error('ProductReview.id is required to patch');
+    }
+    const resource = `/product-reviews/${String(id)}/`;
+    const form = new FormData();
+    if (payload.status !== undefined) {
+      form.set('status', payload.status);
+    }
+    if (payload.rejectionReason !== undefined) {
+      form.set('rejectionReason', payload.rejectionReason ?? '');
+    }
+    if (payload.rating !== undefined) {
+      form.set('rating', String(payload.rating));
+    }
+    if (payload.title !== undefined) {
+      form.set('title', payload.title ?? '');
+    }
+    if (payload.content !== undefined) {
+      form.set('content', payload.content ?? '');
+    }
+    const fetchOptions: RequestOptions = { method: 'PATCH', body: form };
+    fetchOptions.query = [];
+    if (!(options && options.withRights)) {
+      fetchOptions.query.push(['skip_rights', 'y']);
+    }
+    const singularName = (this.constructor as typeof ProductReview)
+      .singularName;
+    return this.merchi.authenticatedFetch(resource, fetchOptions).then(
+      (data: any) => {
+        this.fromJson(ProductReview.normalizeApiJson(data[singularName]));
+        this.cleanDirty();
+        return this;
+      }
+    );
+  }
+}

package/src/entities/production_comment.test.ts

@@ -0,0 +1,7 @@
+import { Merchi } from '../merchi.js';
+
+test('can make ProductionComment', () => {
+  const merchi = new Merchi();
+  const productionComment = new merchi.ProductionComment();
+  expect(productionComment).toBeTruthy();
+});

package/src/entities/production_comment.ts

@@ -0,0 +1,53 @@
+import { Assignment } from './assignment.js';
+import { Entity } from '../entity.js';
+import { MerchiFile } from './file.js';
+import { Notification } from './notification.js';
+import { User } from './user.js';
+
+export class ProductionComment extends Entity {
+  protected static resourceName = 'production_comments';
+  protected static singularName = 'productionComment';
+  protected static pluralName = 'productionComments';
+
+  @ProductionComment.property({type: Date})
+  public archived?: Date | null;
+
+  @ProductionComment.property()
+  public id?: number;
+
+  @ProductionComment.property({type: Date})
+  public date?: Date | null;
+
+  @ProductionComment.property()
+  public urgency?: number;
+
+  @ProductionComment.property()
+  public text?: string;
+
+  @ProductionComment.property()
+  public isUrgentQuestion?: boolean;
+
+  @ProductionComment.property()
+  public sendSms?: boolean;
+
+  @ProductionComment.property()
+  public sendEmail?: boolean;
+
+  @ProductionComment.property()
+  public sendWhatsapp?: boolean;
+
+  @ProductionComment.property({arrayType: "MerchiFile"})
+  public files?: MerchiFile[];
+
+  @ProductionComment.property()
+  public user?: User;
+
+  @ProductionComment.property({arrayType: 'User'})
+  public forwards?: User[];
+
+  @ProductionComment.property({arrayType: 'Notification'})
+  public notifications?: Notification[];
+
+  @ProductionComment.property()
+  public assignment?: Assignment;
+}

package/src/entities/quote.test.ts

@@ -0,0 +1,98 @@
+import { Merchi } from '../merchi.js';
+
+test('can make Quote', () => {
+  const merchi = new Merchi();
+  const quote = new merchi.Quote();
+  expect(quote).toBeTruthy();
+});
+
+test('calculation', () => {
+  const merchi = new Merchi();
+  const quote = new merchi.Quote();
+  const gst = new merchi.CountryTax();
+  gst.taxName = 'GST';
+  gst.taxPercent = 10;
+  const noTax = merchi.CountryTax.getNoTax();
+
+  // quote items did not filled before calculation seems like a embed issue
+  expect(quote.quoteTotal).toThrow();
+  expect(quote.calculateSubTotal).toThrow();
+  expect(quote.calculateTaxAmount).toThrow();
+
+  quote.quoteItems = [new merchi.QuoteItem(), new merchi.QuoteItem()];
+  quote.quoteItems[0].unitPrice = 400;
+  quote.quoteItems[0].quantity = 2;
+  quote.quoteItems[0].taxType = gst;
+  quote.quoteItems[1].unitPrice = 25;
+  quote.quoteItems[1].quantity = 2;
+  quote.quoteItems[1].taxType = noTax;
+
+  // shipments did not filled before calculation seems like a embed issue
+  expect(quote.quoteTotal).toThrow();
+  expect(quote.calculateSubTotal).toThrow();
+  expect(quote.calculateTaxAmount).toThrow();
+
+  quote.shipments = [new merchi.Shipment()];
+  quote.shipments[0].cost = 100;
+  quote.shipments[0].taxType = gst;
+
+  // 800 * 1.1 + 25 * 2 + 100 * 1.1 = 1040
+  expect(quote.quoteTotal()).toBe('1040.000');
+  expect(quote.quoteTotal({'strictEmbed': false})).toBe('1040.000');
+  expect(quote.calculateTotal()).toBe('1040.000');
+  expect(quote.calculateTotal({'strictEmbed': false})).toBe('1040.000');
+
+  // 800 + 25 * 2 + 100
+  expect(quote.calculateSubTotal()).toBe('950.000');
+  expect(quote.calculateSubTotal({'strictEmbed': false})).toBe('950.000');
+
+  // 800 * 0.1 + 100 * 0.1
+  expect(quote.calculateTaxAmount()).toBe('90.000');
+  expect(quote.calculateTaxAmount({'strictEmbed': false})).toBe('90.000');
+});
+
+test('findQuoteItemIndex', () => {
+  const merchi = new Merchi();
+  const quote = new merchi.Quote();
+  expect(() => quote.findQuoteItemIndex(43)).toThrow();
+  quote.quoteItems = [];
+  expect(quote.findQuoteItemIndex(43)).toEqual(-1);
+  quote.quoteItems = [new merchi.QuoteItem()];
+  quote.quoteItems[0].id = 43;
+  expect(quote.findQuoteItemIndex(43)).toEqual(0);
+});
+
+test('removeQuoteItem', () => {
+  const merchi = new Merchi();
+  const quote = new merchi.Quote();
+  const quoteItem = new merchi.QuoteItem();
+  quoteItem.id = 43;
+  expect(() => quote.removeQuoteItem(quoteItem)).toThrow();
+  quoteItem.id = undefined;
+  expect(() => quote.removeQuoteItem(quoteItem)).toThrow();
+  quoteItem.id = 43;
+  quote.quoteItems = [];
+  expect(quote.removeQuoteItem(quoteItem)).toBe(undefined);
+  expect(quote.quoteItems).toEqual([]);
+  quote.quoteItems = [quoteItem];
+  expect(quote.removeQuoteItem(quoteItem)).toBe(undefined);
+  expect(quote.quoteItems).toEqual([]);
+  quoteItem.id = undefined;
+  expect(() => quote.removeQuoteItem(quoteItem)).toThrow();
+});
+
+test('deadlineTimeDifference', () => {
+  const merchi = new Merchi();
+  const quote = new merchi.Quote();
+  expect(quote.deadlineTimeDifference).toThrow();
+  quote.agreedDeadline = null;
+  expect(quote.deadlineTimeDifference).toThrow();
+  quote.assignments = [];
+  expect(quote.deadlineTimeDifference()).toBe(null);
+  quote.assignments = [new merchi.Assignment()];
+  expect(quote.deadlineTimeDifference()).toBe(null);
+  quote.agreedDeadline = new Date(1);
+  expect(quote.deadlineTimeDifference).toThrow();
+  quote.assignments[0].productionDeadline = new Date(2);
+  expect(quote.deadlineTimeDifference()).toEqual(1);
+});

package/src/entities/quote.ts

@@ -0,0 +1,140 @@
+import { Assignment } from './assignment.js';
+import { QuoteItem } from './quote_item.js';
+import { Shipment } from './shipment.js';
+import { Invoice } from './invoice.js';
+import { Entity } from '../entity.js';
+import { kahanSum } from '../util/float.js';
+
+interface CalculateOptions {
+  strictEmbed?: boolean;
+}
+
+export class Quote extends Entity {
+  protected static resourceName = 'quotes';
+  protected static singularName = 'quote';
+  protected static pluralName = 'quotes';
+
+  @Quote.property({type: Date})
+  public archived?: Date | null;
+
+  @Quote.property()
+  public currency?: string;
+
+  @Quote.property()
+  public id?: number;
+
+  @Quote.property({type: Date})
+  public agreedDeadline?: Date | null;
+
+  @Quote.property({arrayType: 'Shipment'})
+  public shipments?: Shipment[];
+
+  @Quote.property({arrayType: 'QuoteItem'})
+  public quoteItems?: QuoteItem[];
+
+  @Quote.property({arrayType: 'Assignment'})
+  public assignments?: Assignment[];
+
+  @Quote.property({type: Invoice})
+  public invoice?: Invoice | null;
+
+  public quoteTotal = (options?: CalculateOptions) => {
+    const { strictEmbed = true } = options ? options : {};
+    const { quoteItems = [], shipments = [] } = this;
+    if (strictEmbed && this.quoteItems === undefined) {
+      throw new Error('quoteItems is undefined, did you forget to embed it?');
+    }
+    if (strictEmbed && this.shipments === undefined) {
+      throw new Error('shipments is undefined, did you forget to embed it?');
+    }
+    const quoteItemsTotal = kahanSum(quoteItems.map((qI: QuoteItem) =>
+      parseFloat(qI.calculateTotal(options)))).toFixed(3);
+    const shipmentItemsTotal = kahanSum(shipments.map((s: Shipment) =>
+      parseFloat(s.calculateTotal(options)))).toFixed(3);
+    return (
+      parseFloat(quoteItemsTotal) + parseFloat(shipmentItemsTotal)
+    ).toFixed(3);
+  };
+
+  public calculateTotal = this.quoteTotal;
+
+  public calculateSubTotal = (options?: CalculateOptions) => {
+    const { strictEmbed = true } = options ? options : {};
+    const { quoteItems = [], shipments = [] } = this;
+    if (strictEmbed && this.quoteItems === undefined) {
+      throw new Error('quoteItems is undefined, did you forget to embed it?');
+    }
+    if (strictEmbed && this.shipments === undefined) {
+      throw new Error('shipments is undefined, did you forget to embed it?');
+    }
+    const quoteItemsTotal = kahanSum(quoteItems.map((qI: QuoteItem) =>
+      parseFloat(qI.calculateSubTotal(options))));
+    const shipmentItemsTotal = kahanSum(shipments.map((s: Shipment) =>
+      parseFloat(s.calculateSubTotal(options))));
+    return (quoteItemsTotal + shipmentItemsTotal).toFixed(3);
+  };
+
+  public calculateTaxAmount = (options?: CalculateOptions) => {
+    const { strictEmbed = true } = options ? options : {};
+    const { quoteItems = [], shipments = [] } = this;
+    if (strictEmbed && this.quoteItems === undefined) {
+      throw new Error('quoteItems is undefined, did you forget to embed it?');
+    }
+    if (strictEmbed && this.shipments === undefined) {
+      throw new Error('shipments is undefined, did you forget to embed it?');
+    }
+    const quoteItemsTotal = kahanSum(quoteItems.map((qI: QuoteItem) =>
+      parseFloat(qI.calculateTaxAmount(options))));
+    const shipmentItemsTotal = kahanSum(shipments.map((s: Shipment) =>
+      parseFloat(s.calculateTaxAmount(options))));
+    return (quoteItemsTotal + shipmentItemsTotal).toFixed(3);
+  };
+
+  public findQuoteItemIndex = (quoteItemId: number) => {
+    if (this.quoteItems === undefined) {
+      throw new Error('quoteItems is undefined, did you forget to embed it?');
+    }
+    function checkEqualId(quoteItem: QuoteItem) {
+      return quoteItem.id === quoteItemId;
+    }
+    return this.quoteItems.findIndex(checkEqualId);
+  };
+
+  public removeQuoteItem = (quoteItem: QuoteItem) => {
+    if (this.quoteItems === undefined) {
+      throw new Error('quoteItems is undefined, did you forget to embed it?');
+    }
+    if (quoteItem.id === undefined) {
+      throw new Error('quoteItem.id is undefined, did you forget to embed it?');
+    }
+    const index = this.findQuoteItemIndex(quoteItem.id);
+    if (index > -1) {
+      this.quoteItems.splice(index, 1);
+    }
+  };
+
+  public deadlineTimeDifference = () => {
+    if (this.agreedDeadline === undefined) {
+      const err = 'agreedDeadline is undefined, did you forget to embed it?';
+      throw new Error(err);
+    }
+    if (this.assignments === undefined) {
+      const err = 'assignments is undefiend, did you forget to embed it?';
+      throw new Error(err);
+    }
+    if (this.assignments.length < 1) {
+      return null;
+    }
+    if (this.agreedDeadline === null) {
+      return null;
+    }
+    const assignment = this.assignments[0];
+    if (assignment.productionDeadline === undefined) {
+      const err = 'productionDeadline is undefined, did you forget to embed' +
+        'it?';
+      throw new Error(err);
+    }
+    const productionDeadline = assignment.productionDeadline;
+    return productionDeadline.valueOf() - this.agreedDeadline.valueOf();
+  };
+}

package/src/entities/quote_item.test.ts

@@ -0,0 +1,50 @@
+import { Merchi } from '../merchi.js';
+
+test('can make QuoteItem', () => {
+  const merchi = new Merchi();
+  const quoteItem = new merchi.QuoteItem();
+  expect(quoteItem).toBeTruthy();
+});
+
+test('total calculation', () => {
+  const merchi = new Merchi();
+  const quoteItem = new merchi.QuoteItem();
+
+  const gst = new merchi.CountryTax();
+  gst.taxName = 'GST';
+  gst.taxPercent = 10;
+  const noTax = merchi.CountryTax.getNoTax();
+
+  quoteItem.unitPrice = 10;
+  quoteItem.quantity = 1;
+
+  // tax type not provided yet should be a embed issue
+  expect(quoteItem.calculateTotal()).toEqual('10.000');
+  expect(quoteItem.calculateTotal({strictEmbed: false})).toEqual('10.000');
+
+  // quote total include tax type properly
+  quoteItem.taxType = gst;
+  expect(quoteItem.calculateTotal()).toEqual('11.000');
+  quoteItem.taxType = noTax;
+  expect(quoteItem.calculateTotal()).toEqual('10.000');
+
+  // null and undefined price and quantity will throw error unless not strictly
+  // require embed
+  quoteItem.unitPrice = null;
+  expect(quoteItem.calculateTotal({strictEmbed: false})).toEqual('0.000');
+
+  quoteItem.unitPrice = 1;
+  quoteItem.quantity = undefined;
+  expect(() => quoteItem.calculateTotal()).toThrow();
+  expect(quoteItem.calculateTotal({strictEmbed: false})).toEqual('0.000');
+
+  quoteItem.unitPrice = undefined;
+  quoteItem.quantity = 1;
+  expect(() => quoteItem.calculateTotal()).toThrow();
+  expect(quoteItem.calculateTotal({strictEmbed: false})).toEqual('0.000');
+
+  // make sure float number recorded correctly
+  quoteItem.quantity = 3.55;
+  quoteItem.unitPrice = 87.12;
+  expect(quoteItem.calculateTotal()).toEqual('309.276');
+});

package/src/entities/quote_item.ts

@@ -0,0 +1,71 @@
+import { CountryTax } from './country_tax.js';
+import { Entity } from '../entity.js';
+import { Quote } from './quote.js';
+
+interface CalculateOptions {
+  strictEmbed?: boolean;
+}
+
+export class QuoteItem extends Entity {
+  protected static resourceName = 'quote_items';
+  protected static singularName = 'quoteItem';
+  protected static pluralName = 'quoteItems';
+
+  @QuoteItem.property({type: Date})
+  public archived?: Date | null;
+
+  @QuoteItem.property()
+  public id?: number;
+
+  @QuoteItem.property()
+  public type?: number;
+
+  @QuoteItem.property()
+  public quantity?: number;
+
+  @QuoteItem.property({type: String})
+  public description?: string | null;
+
+  @QuoteItem.property({type: Number})
+  public unitPrice?: number | null;
+
+  @QuoteItem.property({type: Number})
+  public taxAmount?: number | null;
+
+  @QuoteItem.property({type: CountryTax})
+  public taxType?: CountryTax;
+
+  @QuoteItem.property()
+  public quote?: Quote;
+
+  public calculateSubTotal = (options?: CalculateOptions) => {
+    const { strictEmbed = true } = options ? options : {};
+    if (strictEmbed){
+      if (this.unitPrice === undefined) {
+        throw new Error('unitPrice is undefined, did you forget to embed it?');
+      }
+      if (this.quantity === undefined) {
+        throw new Error('quantity is undefined, did you forget to embed it?');
+      }
+    }
+    const quant = this.quantity ? this.quantity : 0;
+    const unitPrice = this.unitPrice ? this.unitPrice : 0;
+    return (quant * unitPrice).toFixed(3);
+  };
+
+  public calculateTaxAmount = (options?: CalculateOptions) => {
+    const taxPercent = this.taxType && this.taxType.taxPercent ?
+      this.taxType.taxPercent : 0;
+    const taxRate = taxPercent ? Number(taxPercent) / 100 : 0;
+    return (parseFloat(
+      this.calculateSubTotal(options)) * taxRate).toFixed(3);
+  };
+
+  public calculateTotal = (options?: CalculateOptions) => {
+    return (
+      parseFloat(this.calculateSubTotal(options)) +
+      parseFloat(this.calculateTaxAmount(options))
+    ).toFixed(3);
+  };
+
+}

package/src/entities/reminder.test.ts

@@ -0,0 +1,16 @@
+import { Merchi } from '../merchi.js';
+
+test('can make Reminder', () => {
+  const merchi = new Merchi();
+  const reminder = new merchi.Reminder();
+  expect(reminder).toBeTruthy();
+});
+
+test('reminder created date serialised to unix timestamp', () => {
+  const merchi = new Merchi();
+  const reminder = new merchi.Reminder();
+  reminder.created = new Date('Feb 28 2013 19:00:00 GMT-0500');
+  const correct = [['created', '1362096000']];
+  const backData = Array.from((reminder.toFormData() as any).entries());
+  expect(backData).toEqual(correct);
+});