@growupsell/commerce 1.0.0-alpha.1 → 1.0.0-alpha.3

package/dist/checkout-DDNMdKbR.d.ts

@@ -0,0 +1,584 @@
+/** Cart domain types. The backend calculates every total; the library only converts them. */
+/** `delivery` (paid online) or `cod` (cash on delivery). */
+type OrderType = 'delivery' | 'cod';
+/** How the business charges delivery: fixed thresholds, or a delivery partner's quote. */
+type DeliveryChargeType = 'fixed' | 'as_per_delivery_partner';
+/** `none` for stocked goods; others are made to order. Open string: the backend may add modes. */
+type FulfillmentMode = 'none' | 'made_to_order_advance' | 'custom_fixed_price' | (string & {});
+interface CartLine {
+    id: number;
+    /** null for lines without a SKU (made by the merchant). */
+    skuId: number | null;
+    productId: number | null;
+    /** Product name with its variants, e.g. "Iphone 15 (128 GB, Blue)". */
+    name: string;
+    photo: string | null;
+    /** The price when the line was added. */
+    unitPrice: number;
+    /** null when the SKU has no MRP (an MRP of 0 means "not set"), or without a SKU. */
+    mrp: number | null;
+    quantity: number;
+    lineTotal: number;
+    /** Product, category or brand offer amount on this line; 0 otherwise. */
+    offerDiscount: number;
+    taxPercent: number | null;
+    /** min(stock, per-customer limit); null without a SKU. */
+    maxQuantity: number | null;
+    isDigital: boolean;
+    fulfillmentMode: FulfillmentMode;
+    customData: Record<string, unknown> | null;
+    variantIds: number[];
+}
+interface AppliedOffer {
+    id: number;
+    name: string;
+    couponCode: string | null;
+}
+interface AppliedPromoCode {
+    id: number;
+    code: string;
+    type: 'percentage' | 'net';
+    value: number;
+}
+interface Cart {
+    id: number;
+    type: OrderType;
+    lines: CartLine[];
+    subtotal: number;
+    /** The order-level offer amount, or the sum of the line-level offer amounts. */
+    offerDiscount: number;
+    promoDiscount: number;
+    deliveryCharge: number;
+    payable: number;
+    deliveryChargeType: DeliveryChargeType | null;
+    offer: AppliedOffer | null;
+    promoCode: AppliedPromoCode | null;
+    shippingAddressId: number | null;
+    billingAddressId: number | null;
+    /** Made-to-order advance carts: the advance due now. */
+    advanceAmount: number | null;
+}
+/** The totals the backend sends back after the order type changes. */
+interface CartTotals {
+    subtotal: number;
+    deliveryCharge: number;
+    payable: number;
+}
+/** Business tax details for the invoice (legal name and GSTIN). */
+interface TaxDetails {
+    legalName: string;
+    taxNumber: string;
+}
+/** A delivery partner's quote for the cart. */
+interface DeliveryEstimate {
+    deliveryCharge: number;
+    payable: number;
+    /** As the partner sends it (e.g. "Nov 05, 2026"), or null. */
+    estimatedDelivery: string | null;
+}
+
+/**
+ * Catalog domain types: categories, brands and the business's catalog settings.
+ * Built from wire responses in http/catalog.ts.
+ */
+interface Category {
+    id: number;
+    name: string;
+    description: string | null;
+    photo: string | null;
+    parentId: number | null;
+    /** Products in this category and all its sub-categories. */
+    productCount: number;
+}
+/** A category with its sub-categories, as returned by `catalog.categories()`. */
+interface CategoryTree extends Category {
+    /** Newest first. */
+    children: CategoryTree[];
+}
+interface Brand {
+    id: number;
+    name: string;
+    description: string | null;
+    photo: string | null;
+    productCount: number;
+}
+/** Which catalog features the merchant has switched on. Use them to show or hide UI. */
+interface CatalogSettings {
+    reviews: boolean;
+    brands: boolean;
+    categories: boolean;
+    subscriptions: boolean;
+    digitalDelivery: boolean;
+    variants: boolean;
+    specifications: boolean;
+    unitTracking: boolean;
+    manufactureAndExpiryDates: boolean;
+}
+
+/**
+ * Merchant-built product-page content. Built from wire responses in http/productPage.ts.
+ *
+ * Two kinds, both edited by the merchant from the storefront in theme-edit mode:
+ * - **Sections**: titled tabs under the product (e.g. "Description", "FAQs"), each with items.
+ *   An item's `data` holds the components the storefront renders (description, FAQs, features,
+ *   video slider…).
+ * - **Blocks**: one-off content keyed by a slug, e.g. `hero` (the detail layout) and
+ *   `showcase` (vertical video cards).
+ *
+ * `data` is free-form JSON the backend stores as given (apart from the checks listed on
+ * `ProductBlock`), so it is `unknown`: check its shape before use.
+ */
+/**
+ * Which shoppers see a section item:
+ * - `'all'`: every variant.
+ * - `{ skuId, variantIds }`: only this SKU. `variantIds` are its variant options; null when the
+ *   backend did not send them (create and update responses) or the SKU has none.
+ * - `{ variantId }`: every SKU with this variant option, e.g. all "Blue" phones.
+ */
+type ProductSectionItemTarget = 'all' | {
+    skuId: number;
+    variantIds: number[] | null;
+} | {
+    variantId: number;
+};
+/** One item of a section: storefront components, possibly limited to a SKU or variant. */
+interface ProductSectionItem {
+    id: number;
+    sectionId: number;
+    /** As saved by the merchant. The storefront saves a list of `{ slug, … }` components. */
+    data: unknown;
+    /** Position within the section, from 1. */
+    order: number;
+    target: ProductSectionItemTarget;
+}
+/** A titled section of the product page, with its items in display order. */
+interface ProductSection {
+    id: number;
+    productId: number;
+    title: string;
+    items: ProductSectionItem[];
+}
+/**
+ * A slug-keyed content block of a product. The backend checks two slugs:
+ * - `hero`: at most one per product; `data` must be `{ layout: 'default' | 'fullscreen' }`.
+ * - `showcase`: at most one per product; `data` is `{ items: [{ source: 'youtube' | 'upload',
+ *   url, … }] }` with a non-empty url (a valid YouTube link for `youtube`).
+ * Any other slug is stored without checks.
+ */
+interface ProductBlock {
+    id: number;
+    productId: number;
+    slug: string;
+    data: unknown;
+    /** Position among the product's blocks with the same slug, from 1. */
+    order: number;
+}
+
+/**
+ * Product domain types. Built from wire responses in http/products.ts.
+ * Prices are numbers (the backend sends decimal strings such as "58999.00"). Discounts are not
+ * stored here: compute them with `discountPercent()` from `@growupsell/commerce/rules`, so
+ * every app uses the same rule.
+ */
+
+/** One option of a variant group, e.g. "128 GB" in "Storage". */
+interface VariantOption {
+    id: number;
+    label: string;
+    /** False when no SKU with this option can be bought. */
+    available: boolean;
+}
+/** A variant dimension of a product, e.g. Storage or Color. */
+interface VariantGroup {
+    id: number;
+    name: string;
+    options: VariantOption[];
+}
+/** A sellable unit: one combination of variant options, or the product's base SKU. */
+interface ProductSku {
+    id: number;
+    code: string;
+    slug: string;
+    price: number;
+    /** Maximum retail price; null when the merchant did not set one. */
+    mrp: number | null;
+    stockQty: number;
+    active: boolean;
+    /**
+     * The variant options this SKU is made of. Empty for the base SKU, which a product with
+     * variants also has: never offer that one when variants exist.
+     */
+    variantIds: number[];
+}
+/** A row of the product listing: one SKU, with its product's variant groups. */
+interface ProductListItem {
+    skuId: number;
+    productId: number;
+    /** Product name with the SKU's variants, e.g. "Iphone 15 (128 GB, Blue)". */
+    name: string;
+    slug: string;
+    skuCode: string;
+    photos: string[];
+    price: number;
+    mrp: number | null;
+    stockQty: number;
+    taxPercent: number | null;
+    unit: string | null;
+    variantGroups: VariantGroup[];
+    selectedVariantIds: number[];
+    /** The product's description (HTML), for list views; null when empty. */
+    description: string | null;
+    /** `none` for stocked goods; custom modes are made to order. */
+    fulfillmentMode: FulfillmentMode;
+    hasDigitalDelivery: boolean;
+    /** Advance payment required for made-to-order products. */
+    advanceAmount: number | null;
+}
+interface ProductImage {
+    id: number;
+    url: string;
+    /** Full-resolution original, when kept. */
+    originalUrl: string | null;
+    /** The variant option this image shows (e.g. the Blue photos), or null for all. */
+    variantId: number | null;
+    /** The exact SKU this image shows, or null. Use `imagesFor()` to pick a selection's images. */
+    skuId: number | null;
+    /**
+     * A video link (e.g. YouTube) to play instead of the photo, or null. Play it through an
+     * embed URL, never as a raw iframe source (YouTube refuses `watch` URLs in frames).
+     */
+    videoUrl: string | null;
+    order: number;
+}
+/**
+ * Who a specification row applies to. The backend stores rows for every variant, for one
+ * variant option (e.g. "Color = Blue") or for one exact SKU (e.g. a model number). Use
+ * `specificationsFor()` from `@growupsell/commerce/rules` to show the right ones.
+ */
+type SpecificationScope = {
+    type: 'all';
+} | {
+    type: 'variant';
+    variantId: number;
+} | {
+    type: 'sku';
+    skuId: number;
+};
+interface ProductSpecificationGroup {
+    /** e.g. "General", "Display Feature"; null for ungrouped specifications. */
+    name: string | null;
+    items: Array<{
+        key: string;
+        value: string;
+        appliesTo: SpecificationScope;
+    }>;
+}
+interface ProductPolicies {
+    returnDays: number;
+    replacementDays: number;
+    exchangeDays: number;
+    exchangeEnabled: boolean;
+    warrantyMonths: number;
+    guaranteeMonths: number;
+}
+/** A product with everything the product page needs. */
+interface ProductDetail {
+    id: number;
+    name: string;
+    slug: string;
+    description: string | null;
+    /** Editor the description was written with, e.g. `ReactQuill`: tells apps how to render it. */
+    descriptionFormat: string | null;
+    categoryId: number | null;
+    categoryName: string | null;
+    brandId: number | null;
+    taxPercent: number | null;
+    rating: number;
+    reviewCount: number;
+    hasVariants: boolean;
+    images: ProductImage[];
+    variantGroups: VariantGroup[];
+    skus: ProductSku[];
+    specifications: ProductSpecificationGroup[];
+    policies: ProductPolicies | null;
+    availableForSubscription: boolean;
+    hasDigitalDelivery: boolean;
+    fulfillmentMode: FulfillmentMode;
+    advanceAmount: number | null;
+}
+/** A product as listed by `products.list()` (home sliders, product pickers). */
+interface ProductOverview {
+    id: number;
+    name: string;
+    slug: string;
+    /** HTML, written with the editor the product detail's `descriptionFormat` names; null when empty. */
+    description: string | null;
+    /**
+     * `none` for stocked goods; custom modes are made to order and never out of stock (pass it to
+     * `purchaseLimit()` with a SKU's `stockQty` for the stock badge).
+     */
+    fulfillmentMode: FulfillmentMode;
+    categoryName: string | null;
+    images: ProductImage[];
+    variantGroups: VariantGroup[];
+    skus: ProductSku[];
+    /** Lowest SKU price. */
+    priceFrom: number | null;
+    unit: string | null;
+}
+/**
+ * Order of `products.list()`. The backend orders this list by id only (no creation date), so
+ * `newest` is the highest id first. Without `sort` the backend's default applies: `oldest`.
+ */
+type ProductListSort = 'newest' | 'oldest' | 'name-a-z' | 'name-z-a';
+interface ProductListOptions {
+    ids?: readonly number[];
+    /** Includes sub-categories. */
+    categoryIds?: readonly number[];
+    sort?: ProductListSort;
+    /** Default 20. */
+    limit?: number;
+    offset?: number;
+}
+interface ProductFilterConfig {
+    /** Price range across the business's products. */
+    price: {
+        min: number;
+        max: number;
+    };
+    /** Specification filters; pass selections back as `specifications` to `products.search()`. */
+    specifications: Array<{
+        id: number;
+        name: string;
+        type: string;
+        options: string[];
+    }>;
+}
+/** A quick-search suggestion: a product or a category. */
+type SearchSuggestion = {
+    type: 'product';
+    id: number;
+    name: string;
+    categoryName: string | null;
+    image: string | null;
+} | {
+    type: 'category';
+    id: number;
+    name: string;
+};
+/** One page of a list. */
+interface Page<T> {
+    items: T[];
+    /** Total across all pages. */
+    total: number;
+    offset: number;
+    limit: number;
+}
+/** Listing order. `newest` is the default. */
+type ProductSort = 'price-low-to-high' | 'price-high-to-low' | 'newest' | 'popularity' | 'category';
+interface ProductSearchOptions {
+    /** Free-text search over name and related fields. */
+    search?: string;
+    /** Includes sub-categories. */
+    categoryIds?: readonly number[];
+    brandIds?: readonly number[];
+    /** Variant option labels, e.g. ["Blue", "128 GB"]. */
+    variantLabels?: readonly string[];
+    /** Specification filters from `filterConfig()`: AND across ids, OR within one id's values. */
+    specifications?: ReadonlyArray<{
+        id: number;
+        values: readonly string[];
+    }>;
+    minPrice?: number;
+    maxPrice?: number;
+    minDiscountPercent?: number;
+    minRating?: number;
+    sortBy?: ProductSort;
+    /** Default 20. */
+    limit?: number;
+    offset?: number;
+}
+
+/** Offers, promo codes, gift cards and reward points. */
+/** What an offer applies to: the whole order, or matching products, categories or brands. */
+type OfferScope = 'order' | 'product' | 'category' | 'brand';
+interface Offer {
+    id: number;
+    name: string;
+    description: string | null;
+    image: string | null;
+    type: 'percentage' | 'net';
+    /** Percent off, for `percentage` offers. */
+    percentOff: number;
+    /** The fixed amount off, for `net` offers. */
+    amountOff: number;
+    minOrderAmount: number;
+    startsAt: string;
+    endsAt: string;
+    couponCode: string | null;
+    scope: OfferScope;
+    isActive: boolean;
+}
+interface PromoCode {
+    id: number;
+    code: string;
+    description: string | null;
+    type: 'percentage' | 'net';
+    value: number;
+    expiresAt: string;
+    status: 'active' | 'expired' | 'redeemed';
+}
+/** The PIN is never kept: the backend returns it unmasked, the library drops it. */
+interface GiftCard {
+    id: number;
+    code: string;
+    amount: number;
+    usedAmount: number;
+    issuedAt: string;
+}
+interface RewardPointSettings {
+    /** Reward points are switched on, for orders too. */
+    enabled: boolean;
+    /** Points earned per currency unit paid. */
+    pointsPerCurrencyUnit: number;
+    /** The value of one point when spent. */
+    currencyPerPoint: number;
+    /** Points given on sign-up. */
+    signupPoints: number;
+}
+
+/**
+ * Product review domain types. Built from wire responses in http/reviews.ts.
+ * Ratings are numbers from 1 to 5 in steps of 0.5 (the backend stores one decimal and sends it
+ * as a string such as "4.5").
+ */
+/** A review as the backend stores it: what `create()` and `update()` return. */
+interface Review {
+    id: number;
+    productId: number;
+    /** The customer who wrote it: compare with the logged-in customer to offer edit and delete. */
+    customerId: number;
+    title: string;
+    message: string | null;
+    /** URL of the photo attached to the review. */
+    photo: string | null;
+    /** Null for old reviews saved without a rating. */
+    rating: number | null;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+}
+/** The business's reply to a review. */
+interface ReviewReply {
+    id: number;
+    message: string;
+    /** Name of the staff member who replied. */
+    authorName: string | null;
+    authorPhoto: string | null;
+}
+/** A published review, as listed on product pages and the home page. */
+interface ReviewListItem extends Review {
+    productName: string;
+    /** Full name, or the company name for business customers. */
+    customerName: string | null;
+    customerPhoto: string | null;
+    reply: ReviewReply | null;
+}
+/** Rating summary of one product. */
+interface ReviewSummary {
+    reviewCount: number;
+    /** Average of all ratings, rounded to one decimal; 0 without reviews. */
+    averageRating: number;
+    /**
+     * Number of reviews per whole star. Half-star ratings (e.g. 4.5) are counted in no bucket by
+     * the backend, so these may add up to less than `reviewCount`.
+     */
+    starCounts: {
+        1: number;
+        2: number;
+        3: number;
+        4: number;
+        5: number;
+    };
+}
+/** Whether the logged-in customer may review a product. */
+type ReviewEligibility = {
+    canReview: true;
+    /** The ordered item the review is for: pass it to `reviews.create()`. */
+    orderProductId: number;
+} | {
+    canReview: false;
+    orderProductId: null;
+};
+
+/** Customer domain types. Built from wire responses in http/auth.ts and http/customer.ts. */
+/** The logged-in customer's own profile. */
+interface CustomerProfile {
+    id: number;
+    type: 'individual' | 'business';
+    firstName: string | null;
+    lastName: string | null;
+    email: string | null;
+    /** E.164, e.g. "+919876543210". */
+    phone: string | null;
+    businessName: string | null;
+    taxNumber: string | null;
+    /** Profile photo URL. */
+    photo: string | null;
+    isActive: boolean;
+    emailVerified: boolean;
+    phoneVerified: boolean;
+}
+
+/** The business's order settings: what checkout may offer. */
+interface CheckoutSettings {
+    allowCashOnDelivery: boolean;
+    /** Customers may cancel their own orders. */
+    allowCancellation: boolean;
+    /** New orders are accepted without the merchant confirming them. */
+    autoAccept: boolean;
+    onlineOrdersEnabled: boolean;
+    deliveryChargeEnabled: boolean;
+    /** Most units of one SKU an individual customer may order. */
+    maxQuantityIndividual: number;
+    /** Most units of one SKU a business customer may order. */
+    maxQuantityBusiness: number;
+}
+/** How a payment is made. Open string: the backend may add methods. */
+type PaymentMethodType = 'razorpay' | 'stripe' | 'phonepe' | 'direct-transfer' | 'cashfree' | 'paytm' | 'upi' | 'cash' | 'swipe-machine' | (string & {});
+/**
+ * What is still to pay after placing an order. `method` says which payment SDK the app runs;
+ * then it confirms through `client.payments`.
+ */
+interface PendingPayment {
+    /** Pass this to `client.payments.*`. */
+    id: number;
+    amount: number;
+    method: PaymentMethodType | null;
+    /** The provider's public key: Razorpay key id, Stripe publishable key. */
+    publicKey: string | null;
+    /** The provider's order: Razorpay order id, Stripe PaymentIntent id. */
+    providerOrderId: string | null;
+    /** Stripe only: the PaymentIntent's client secret for Stripe Elements. */
+    clientSecret: string | null;
+    /** PhonePe only: the page to send the shopper to. */
+    redirectUrl: string | null;
+}
+/**
+ * The result of placing an order. `placed` also covers cash on delivery and orders fully paid
+ * by gift cards or reward points.
+ */
+type PlaceOrderResult = {
+    status: 'placed';
+    orderId: number;
+} | {
+    status: 'payment-required';
+    orderId: number;
+    payment: PendingPayment;
+};
+/** A made-to-order product's new order and the advance to pay now. */
+interface AdvanceOrder {
+    orderId: number;
+    payment: PendingPayment;
+}
+
+export type { AdvanceOrder as A, Brand as B, Cart as C, DeliveryChargeType as D, ProductSectionItem as E, FulfillmentMode as F, GiftCard as G, ProductSectionItemTarget as H, ProductSku as I, ProductSort as J, ProductSpecificationGroup as K, PromoCode as L, ReviewEligibility as M, ReviewListItem as N, Offer as O, Page as P, ReviewReply as Q, Review as R, ReviewSummary as S, RewardPointSettings as T, SearchSuggestion as U, SpecificationScope as V, TaxDetails as W, VariantGroup as X, VariantOption as Y, AppliedOffer as a, AppliedPromoCode as b, CartLine as c, CartTotals as d, CatalogSettings as e, Category as f, CategoryTree as g, CheckoutSettings as h, CustomerProfile as i, DeliveryEstimate as j, OfferScope as k, OrderType as l, PaymentMethodType as m, PendingPayment as n, PlaceOrderResult as o, ProductBlock as p, ProductDetail as q, ProductFilterConfig as r, ProductImage as s, ProductListItem as t, ProductListOptions as u, ProductListSort as v, ProductOverview as w, ProductPolicies as x, ProductSearchOptions as y, ProductSection as z };