@nymbalhq/types 1.4.0 → 1.6.0

package/dist/index.js

@@ -19,7 +19,7 @@ var ConfigError = class extends NymbalError {
 };
 var ValidationError = class extends NymbalError {
   constructor(message, options = {}) {
-    super("validation.failed", message, options);
+    super(options.code ?? "validation.failed", message, options);
   }
 };
 var NotFoundError = class extends NymbalError {
@@ -63,6 +63,26 @@ var CheckoutError = class extends NymbalError {
     super(`checkout.${code}`, message, options);
   }
 };
+var CartLimitError = class extends NymbalError {
+  constructor(variantId, max, onCart) {
+    super("cart.qty_limit", `a cart line holds at most ${max}`, {
+      context: { variantId, max, onCart }
+    });
+  }
+};
+var REVIEW_REFUSAL_MESSAGES = {
+  submit_unsupported: "This store does not take reviews on its site.",
+  already_reviewed: "You have already reviewed this product.",
+  not_a_buyer: "Only a customer who bought this product can review it.",
+  rejected: "The review was not accepted."
+};
+var ReviewRefusedError = class extends NymbalError {
+  refusal;
+  constructor(refusal, message = REVIEW_REFUSAL_MESSAGES[refusal], options = {}) {
+    super(`reviews.${refusal}`, message, options);
+    this.refusal = refusal;
+  }
+};
 var StatusTransitionError = class extends NymbalError {
   constructor(entity, fromStatus, toStatus, options = {}) {
     super(
@@ -150,6 +170,9 @@ var PRODUCT_SORT_LABELS = {
   "name-desc": "Name: Z to A"
 };
 
+// src/domain/cart.ts
+var CART_LINE_MAX_QTY = 99;
+
 // src/domain/order.ts
 var ORDER_STATUS_TRANSITIONS = {
   pending: ["confirmed", "cancelled"],
@@ -169,7 +192,12 @@ function assertOrderTransition(from, to) {
     throw new StatusTransitionError("order", from, to);
   }
 }
+function agentSource(name) {
+  return `agent:${name}`;
+}
 var ORDER_KEY_HEADER = "x-nymbal-order-key";
+var ORDER_EMAIL_HEADER = "x-nymbal-order-email";
+var SHOPPER_ATTESTATION_HEADER = "x-nymbal-shopper";
 function paymentState(order) {
   if (order.capturedMinor <= 0) return "unpaid";
   if (order.refundedMinor <= 0) return "paid";
@@ -213,6 +241,7 @@ var EVT_ORDER_REFUNDED = "order.refunded.v1";
 var EVT_ORDER_PARTIALLY_REFUNDED = "order.partially_refunded.v1";
 var EVT_ORDER_STATUS_CHANGED = "order.status_changed.v1";
 var EVT_ORDER_CONFIRMATION_RESEND_REQUESTED = "order.confirmation_resend_requested.v1";
+var EVT_ORDER_DELETED = "order.deleted.v1";
 var EVT_INVENTORY_CHANGED = "inventory.changed.v1";
 var EVT_INVENTORY_RESERVED = "inventory.reserved.v1";
 var EVT_INVENTORY_RELEASED = "inventory.released.v1";
@@ -234,9 +263,17 @@ var EVT_PAYMENT_CAPTURED = "payment.captured.v1";
 var EVT_PAYMENT_FAILED = "payment.failed.v1";
 var EVT_PAYMENT_REFUNDED = "payment.refunded.v1";
 var EVT_ALERT_REQUESTED = "alert.requested.v1";
+var EVT_ALERT_REPEATED = "alert.repeated.v1";
 var EVT_ALERT_CONFIRMED = "alert.confirmed.v1";
 var EVT_ALERT_UNSUBSCRIBED = "alert.unsubscribed.v1";
 var EVT_ALERT_SENT = "alert.sent.v1";
+var EVT_ALERT_CONFIRMATION_SENT = "alert.confirmation_sent.v1";
+var EVT_REVIEW_SUBMITTED = "review.submitted.v1";
+var EVT_PROPOSAL_CREATED = "proposal.created.v1";
+var EVT_PROPOSAL_APPROVED = "proposal.approved.v1";
+var EVT_PROPOSAL_REJECTED = "proposal.rejected.v1";
+var EVT_PROPOSAL_APPLIED = "proposal.applied.v1";
+var EVT_PROPOSAL_FAILED = "proposal.failed.v1";
 var EVT_ADAPTER_ERROR = "adapter.error.v1";
 var EVT_SETTINGS_CHANGED = "settings.changed.v1";
 var STANDARD_EVENT_TYPES = [
@@ -261,6 +298,7 @@ var STANDARD_EVENT_TYPES = [
   EVT_ORDER_PARTIALLY_REFUNDED,
   EVT_ORDER_STATUS_CHANGED,
   EVT_ORDER_CONFIRMATION_RESEND_REQUESTED,
+  EVT_ORDER_DELETED,
   EVT_INVENTORY_CHANGED,
   EVT_INVENTORY_RESERVED,
   EVT_INVENTORY_RELEASED,
@@ -281,9 +319,17 @@ var STANDARD_EVENT_TYPES = [
   EVT_PAYMENT_FAILED,
   EVT_PAYMENT_REFUNDED,
   EVT_ALERT_REQUESTED,
+  EVT_ALERT_REPEATED,
   EVT_ALERT_CONFIRMED,
   EVT_ALERT_UNSUBSCRIBED,
   EVT_ALERT_SENT,
+  EVT_ALERT_CONFIRMATION_SENT,
+  EVT_REVIEW_SUBMITTED,
+  EVT_PROPOSAL_CREATED,
+  EVT_PROPOSAL_APPROVED,
+  EVT_PROPOSAL_REJECTED,
+  EVT_PROPOSAL_APPLIED,
+  EVT_PROPOSAL_FAILED,
   EVT_ADAPTER_ERROR,
   EVT_SETTINGS_CHANGED
 ];
@@ -354,7 +400,7 @@ async function boundedHealthCheck(check, options = {}) {
 }
 
 // src/adapters/document-order.ts
-var collator = new Intl.Collator(void 0, { sensitivity: "base" });
+var collator;
 function rankOf(value) {
   if (typeof value === "number") return 0;
   if (typeof value === "string") return 1;
@@ -381,6 +427,7 @@ function compareDocumentValues(a, b) {
     case 0:
       return sign(a - b);
     case 1:
+      collator ??= new Intl.Collator(void 0, { sensitivity: "base" });
       return sign(collator.compare(a, b));
     case 2:
       return sign(compareOther(a, b));
@@ -512,6 +559,9 @@ function buildSecurityHeaders(security) {
   return headers;
 }
 
+// src/adapters/commerce.ts
+var SHIPPING_CAPABILITIES = ["rates", "labels", "tracking"];
+
 // src/adapters/webhook-delivery.ts
 var VERSIONED_EVENT = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*\.v[1-9][0-9]*$/;
 function isPlainObject(value) {
@@ -545,6 +595,82 @@ function webhookDeliveryProblem(providerName, producesEvents, delivery) {
   return null;
 }
 
+// src/adapters/email-feedback.ts
+function emailFeedbackType(providerName, what) {
+  return `${providerName}.${what}.v1`;
+}
+function payloadOf(event) {
+  const payload = event?.payload;
+  return typeof payload === "object" && payload !== null ? payload : {};
+}
+function emailFeedbackProblem(providerName, delivery) {
+  const bounced = emailFeedbackType(providerName, "bounced");
+  const complained = emailFeedbackType(providerName, "complained");
+  if (!Array.isArray(delivery.events)) return null;
+  for (const event of delivery.events) {
+    const type = event?.type;
+    if (type !== bounced && type !== complained) continue;
+    const payload = payloadOf(event);
+    const { recipient, messageId, occurredAt } = payload;
+    if (typeof recipient !== "string" || recipient.trim() === "") {
+      return { type, reason: "the recipient is missing or empty" };
+    }
+    if (type === bounced && payload["bounce"] !== "hard" && payload["bounce"] !== "soft") {
+      return { type, reason: "the bounce is neither 'hard' nor 'soft'" };
+    }
+    if (messageId !== null && typeof messageId !== "string") {
+      return { type, reason: "the messageId is neither a string nor null" };
+    }
+    if (typeof occurredAt !== "string" || Number.isNaN(Date.parse(occurredAt))) {
+      return { type, reason: "occurredAt is not a readable date" };
+    }
+  }
+  return null;
+}
+
+// src/adapters/shipping-tracking.ts
+var SHIPPING_TRACKING_STATUSES = [
+  "pre_transit",
+  "in_transit",
+  "out_for_delivery",
+  "delivered",
+  "exception",
+  "returned",
+  "unknown"
+];
+function shippingTrackingType(providerName) {
+  return `${providerName}.tracking.v1`;
+}
+function normaliseTrackingNumber(value) {
+  return value.replace(/\s+/g, "").toUpperCase();
+}
+function payloadOf2(event) {
+  const payload = event?.payload;
+  return typeof payload === "object" && payload !== null ? payload : {};
+}
+function shippingTrackingProblem(providerName, delivery) {
+  const tracking = shippingTrackingType(providerName);
+  if (!Array.isArray(delivery.events)) return null;
+  for (const event of delivery.events) {
+    const type = event?.type;
+    if (type !== tracking) continue;
+    const { trackingNumber, carrier, status, occurredAt } = payloadOf2(event);
+    if (typeof trackingNumber !== "string" || normaliseTrackingNumber(trackingNumber) === "") {
+      return { type, reason: "the trackingNumber is missing or empty" };
+    }
+    if (carrier !== null && typeof carrier !== "string") {
+      return { type, reason: "the carrier is neither a string nor null" };
+    }
+    if (!SHIPPING_TRACKING_STATUSES.includes(status)) {
+      return { type, reason: "the status is not one of the tracking statuses" };
+    }
+    if (typeof occurredAt !== "string" || Number.isNaN(Date.parse(occurredAt))) {
+      return { type, reason: "occurredAt is not a readable date" };
+    }
+  }
+  return null;
+}
+
 // src/adapters/email-templates.ts
 function render(template, vars) {
   return template.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, path) => {
@@ -572,10 +698,14 @@ We'll let you know when it ships.{{orderLink}}`
   },
   "order-shipped": {
     subject: "Order {{orderNumber}} is on its way",
+    // `trackingLink` and `orderLink` are whole paragraphs, absent for an unknown carrier or a store with no URL.
     body: `Hi {{customerName}},
 
 Your order {{orderNumber}} has shipped via {{carrier}}.
-Tracking: {{trackingNumber}}`
+Tracking: {{trackingNumber}}{{trackingLink}}
+
+In this parcel:
+{{itemsList}}{{orderLink}}`
   },
   welcome: {
     subject: "Welcome to {{storeName}}",
@@ -670,16 +800,28 @@ var IDEMPOTENT_REPLAYED_HEADER = "idempotent-replayed";
 function isValidIdempotencyKey(value) {
   return /^[A-Za-z0-9._:-]{1,128}$/.test(value);
 }
+
+// src/proposals.ts
+var PREVIEWED_COMMANDS = [
+  "product.update",
+  "inventory.adjust",
+  "order.refund",
+  "order.cancel"
+];
 export {
   AdapterError,
   AuthError,
+  CART_LINE_MAX_QTY,
   CORRELATION_ID_HEADER,
+  CartLimitError,
   CheckoutError,
   ConfigError,
   DEFAULT_PRODUCT_SORT,
   DEFAULT_QUERY_LIMIT,
   EVT_ADAPTER_ERROR,
+  EVT_ALERT_CONFIRMATION_SENT,
   EVT_ALERT_CONFIRMED,
+  EVT_ALERT_REPEATED,
   EVT_ALERT_REQUESTED,
   EVT_ALERT_SENT,
   EVT_ALERT_UNSUBSCRIBED,
@@ -703,6 +845,7 @@ export {
   EVT_INVENTORY_RESERVED,
   EVT_ORDER_CANCELLED,
   EVT_ORDER_CONFIRMATION_RESEND_REQUESTED,
+  EVT_ORDER_DELETED,
   EVT_ORDER_DELIVERED,
   EVT_ORDER_FULFILLED,
   EVT_ORDER_PAID,
@@ -723,6 +866,12 @@ export {
   EVT_PRODUCT_UPDATED,
   EVT_PRODUCT_VARIANT_PRICE_CHANGED,
   EVT_PRODUCT_VIEWED,
+  EVT_PROPOSAL_APPLIED,
+  EVT_PROPOSAL_APPROVED,
+  EVT_PROPOSAL_CREATED,
+  EVT_PROPOSAL_FAILED,
+  EVT_PROPOSAL_REJECTED,
+  EVT_REVIEW_SUBMITTED,
   EVT_SETTINGS_CHANGED,
   EVT_VISITOR_MERGED,
   HEALTH_CHECK_TIMEOUT_MS,
@@ -731,19 +880,26 @@ export {
   IDEMPOTENT_REPLAYED_HEADER,
   NotFoundError,
   NymbalError,
+  ORDER_EMAIL_HEADER,
   ORDER_KEY_HEADER,
   ORDER_STATUS_TRANSITIONS,
   ORDER_TIMELINE_KINDS,
   OrderConflictError,
+  PREVIEWED_COMMANDS,
   PRODUCT_SORT_KEYS,
   PRODUCT_SORT_LABELS,
   PaymentError,
+  ReviewRefusedError,
   SECRET_MIN_LENGTH,
+  SHIPPING_CAPABILITIES,
+  SHIPPING_TRACKING_STATUSES,
+  SHOPPER_ATTESTATION_HEADER,
   STANDARD_EVENT_TYPES,
   STOCK_LABELS,
   StatusTransitionError,
   ValidationError,
   add,
+  agentSource,
   allocate,
   assertMinorUnits,
   assertOrderTransition,
@@ -754,6 +910,8 @@ export {
   connectionSecrets,
   displayUrl,
   documentValueAt,
+  emailFeedbackProblem,
+  emailFeedbackType,
   errorText,
   handlerFailedError,
   isValidCorrelationId,
@@ -761,10 +919,13 @@ export {
   matchesSortKey,
   money,
   mulBy,
+  normaliseTrackingNumber,
   paymentState,
   queryDocuments,
   refundableMinor,
   renderEmailTemplate,
+  shippingTrackingProblem,
+  shippingTrackingType,
   stockLevel,
   sub,
   sumMoney,