@webround/commerce 0.0.0-stage → 0.3.0

package/dist/cart/types.d.ts

@@ -0,0 +1,194 @@
+/** One line of a cart: which variant, at which of its prices, how many. */
+export interface CartLineInput {
+    variantId: string;
+    priceId: string;
+    quantity: number;
+}
+/**
+ * An option of a line (size, colour…), in one of two shapes, because the store makes it in two places. What `total` answers for a guest's lines is read from the catalog in the language asked:
+ * `tagValue` is the value in that language (`tagValueAlias` is `null` there). What a customer's cart (`get`) answers is what was SAVED when the line was added: `optionValue`, the value as the
+ * store keeps it (in its default language), and no alias. They are not the same thing; which one a line has is told by the key it has.
+ */
+export type CartItemOption = {
+    optionName: string;
+    tagValue: string;
+    tagValueAlias: string | null;
+} | {
+    optionName: string;
+    optionValue: string;
+};
+/** `pricing` of a zone or a method: by currency, as the store writes it (what a checkout reads). */
+type ByCurrency = Record<string, unknown>;
+export interface CartShippingZone {
+    id: string;
+    label: string;
+    countryCode: string;
+    surchargePricing: ByCurrency;
+    taxRate: number;
+    /** Seen absent in a real cart: the store leaves these out of the zones it puts in a cart. */
+    stripeTaxRateId?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface CartShippingMethod {
+    id: string;
+    /** Seen in a real cart, undocumented: which method this is. */
+    methodId?: string;
+    assetUrl?: string | null;
+    label: string;
+    provider: string | null;
+    availableCountries?: string[] | null;
+    etaMin: number | null;
+    etaMax: number | null;
+    enabled: boolean;
+    pricing: ByCurrency;
+    maxWeight: number | null;
+    maxVolume: number | null;
+    assetId: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+}
+export interface CartTaxZone {
+    id: string;
+    label: string;
+    rate: number;
+    countryCode: string;
+    isDefault: boolean;
+    stripeTaxRateId?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+}
+/** A line of a priced cart. `id` is the line's own (a customer's cart has it; what `total` answers for a guest does not). */
+export interface CartItem {
+    id?: string;
+    variantId: string;
+    priceId: string;
+    productId: string;
+    variantName: string | null;
+    productName: string | null;
+    variantSlug: string;
+    skuCode: string | null;
+    coverUrl: string | null;
+    quantity: number;
+    originalPrice: number;
+    comparePrice: number;
+    netAmount: number;
+    totalAmount: number;
+    grossAmount: number;
+    totalGrossAmount: number;
+    taxRate: number;
+    defaultTaxRate: number;
+    currencyCode: string;
+    cadence: string | null;
+    isAvailable: boolean;
+    available: number;
+    options: CartItemOption[];
+    shippingZones: CartShippingZone[];
+    shippingMethods: CartShippingMethod[];
+    taxZones: CartTaxZone[];
+    resolvedZone: CartTaxZone | null;
+    deliveryMethods: string[];
+    allowBackorder: boolean;
+    purchaseRestock: boolean;
+    allowFreeShipping: boolean;
+    forceFreeShipping: boolean;
+    packageWeight?: number;
+    packageLength?: number;
+    packageWidth?: number;
+    packageHeight?: number;
+    packageVolume?: number;
+}
+/**
+ * A priced cart: the customer's (`get`) or the one the lines of a guest make (`total`). The two totals count ONLY the lines that are available (`isAvailable`): a cart of lines that are all out of stock
+ * has the total 0 though each line has its own price. A variant the store does not have is left out of `total`'s answer, not refused.
+ */
+export interface Cart {
+    items: CartItem[];
+    totalAmount: number;
+    totalGrossAmount: number;
+}
+export interface GetCartInput {
+    langCode?: string;
+    /** Identifies this cart for the store's analytics (an abandoned cart): made and kept by the client. */
+    cartTrackingId?: string;
+}
+export interface CartTotalInput {
+    langCode?: string;
+    /** Up to 100 lines. */
+    items: CartLineInput[];
+    cartTrackingId?: string;
+}
+export interface MergeCartInput {
+    langCode?: string;
+    /** Up to 100 lines. A variant the customer's cart already has is added to. */
+    items: CartLineInput[];
+}
+export interface UpdateCartItemInput {
+    quantity: number;
+}
+/** What adding a line answers: the line was made (`created`) or was already there and its quantity grew (`updated`, with the quantity it has now). */
+export interface CartItemAction {
+    created?: boolean;
+    updated?: boolean;
+    deleted?: boolean;
+    quantity?: number;
+}
+/** `fallbackApplied`: the lines had more than one currency or billing cadence, and the store had to fall back to one. */
+export interface CartMergeAnswer {
+    merged: boolean;
+    fallbackApplied: boolean;
+}
+export interface VerifyPromotionsInput {
+    /** 1 to 10 codes: none, or one the store does not know, is 404 `PROMOTION_INVALID`. */
+    codes: string[];
+    /** The cart's gross total as a TEXT of digits with up to 8 decimals (`"123.45"`): that is how the store wants it. */
+    cartTotal: string;
+    cartCurrency: string;
+    variantIds: string[];
+    langCode?: string;
+}
+export interface Promotion {
+    id: string;
+    name: string;
+    /** Not in what the cart's promotion check answers (the store selects fewer columns than it declares). */
+    description?: string | null;
+    active?: boolean;
+    target: string;
+    code: string | null;
+    position: number;
+    discountType: string;
+    /** `{ base }` for a percentage; by currency (`{ EUR: { base } }`) for a fixed amount. */
+    discountValue: {
+        base: number;
+    } | Record<string, {
+        base: number;
+    }> | null;
+    limitUsageGlobal: boolean;
+    limitUsageCustomer: boolean;
+    maxUsesGlobal: number | null;
+    maxUsesPerCustomer: number | null;
+    minOrderAmount: Record<string, {
+        base: number;
+    }> | null;
+    exclusive: boolean;
+    reserved: boolean;
+    filterMode: string;
+    startsAt: string | null;
+    endsAt: string | null;
+    createdAt: string;
+    updatedAt?: string | null;
+}
+export interface VerifyPromotionsAnswer {
+    data: Promotion[];
+    valid: boolean;
+}
+/** The `code` the store gives to what the cart refuses (`CommerceError.code`). */
+export declare const CART_ERROR_CODES: {
+    /** A cart has one currency and one billing cadence. */
+    readonly currencyMismatch: "CART_CURRENCY_MISMATCH";
+    /** A cart has a limited number of different variants (99 by default). */
+    readonly limitReached: "CART_LIMIT_REACHED";
+    readonly invalidItems: "CART_INVALID_ITEMS";
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/cart/types.js

@@ -0,0 +1,11 @@
+// What the cart's calls of commerce-core take and give, as the store says it (the shapes are its own: nothing is renamed, reshaped or completed). Dates come as text, as JSON has them. What a customer's cart is made
+// of (a variant, one of its prices, how many) is the same for a customer's and a guest's: a guest's lives in the page and is priced by `total`.
+/** The `code` the store gives to what the cart refuses (`CommerceError.code`). */
+export const CART_ERROR_CODES = {
+    /** A cart has one currency and one billing cadence. */
+    currencyMismatch: 'CART_CURRENCY_MISMATCH',
+    /** A cart has a limited number of different variants (99 by default). */
+    limitReached: 'CART_LIMIT_REACHED',
+    invalidItems: 'CART_INVALID_ITEMS',
+};
+//# sourceMappingURL=types.js.map

package/dist/catalog/cached.d.ts

@@ -0,0 +1,47 @@
+import { type Cache } from '../cache.js';
+import { type Resource } from '../resource.js';
+import type { HttpClient } from '../http.js';
+import { type Catalog } from './catalog.js';
+import type { ProductByIdInput, ProductBySlugInput, ProductDetailResponse, ProductPage, ProductRelatedInput, ProductReviewsInput, ProductSearch, ReviewPage, StoreDataResponse } from './types.js';
+/** What can be forgotten from the cache: one of the catalog's calls. */
+export type CatalogCall = 'products.search' | 'products.getBySlug' | 'products.getById' | 'products.getReviews' | 'products.getRelated' | 'storeData.get';
+export type { Resource };
+export interface CatalogResources {
+    products: {
+        search(input: ProductSearch): Resource<ProductPage>;
+        getBySlug(variantSlug: string, input: ProductBySlugInput): Resource<ProductDetailResponse>;
+        getById(id: string, input: ProductByIdInput): Resource<ProductDetailResponse>;
+        getReviews(id: string, input?: ProductReviewsInput): Resource<ReviewPage>;
+        getRelated(id: string, input: ProductRelatedInput): Resource<ProductPage>;
+    };
+    storeData: {
+        get(input?: {
+            langCode?: string;
+        }): Resource<StoreDataResponse>;
+    };
+}
+/**
+ * What to forget. `call` alone: everything that was asked of that call. With `subject`: only what it was asked about (the product's id for `getById`, `getReviews`, `getRelated`; the VARIANT's slug
+ * for `getBySlug`). The search and the store data are about nothing in particular, so they take no subject.
+ */
+export type CatalogForget = {
+    call: 'products.search' | 'storeData.get';
+} | {
+    call: 'products.getBySlug' | 'products.getById' | 'products.getReviews' | 'products.getRelated';
+    subject?: string;
+};
+export interface CachedCatalog extends Catalog {
+    resource: CatalogResources;
+    /** Forgets what was asked of the catalog, so that the next question is asked again: of one call, of one call about one subject, or (with nothing said) all that this store has in the cache. */
+    invalidate(target?: CatalogForget): void;
+}
+/** What tells one store's questions from another's in the cache: where the backend is, and which store. A client has them (`HttpClient`); a catalog that does not use one says them itself. */
+export type CatalogIdentity = Pick<HttpClient, 'baseUrl' | 'storeId'>;
+/**
+ * The catalog, remembered. With a client (`createCachedCatalog(http, cache)`) it asks the REST catalog. With an `identity` and a `catalog` of its own
+ * (`createCachedCatalog({ baseUrl, storeId }, cache, catalog)`) it remembers whatever answers the `Catalog` interface (a GraphQL one, one for tests): the cache,
+ * the resources and what a framework binds to them are the same, for they depend on the interface and on who is asking, never on how it is asked.
+ */
+export declare function createCachedCatalog(http: HttpClient, cache: Cache): CachedCatalog;
+export declare function createCachedCatalog(identity: CatalogIdentity, cache: Cache, catalog: Catalog): CachedCatalog;
+//# sourceMappingURL=cached.d.ts.map

package/dist/catalog/cached.js

@@ -0,0 +1,52 @@
+import { cachePrefix } from '../cache.js';
+import { createResourceFactory } from '../resource.js';
+import { createCatalog } from './catalog.js';
+import { named } from './named.js';
+export function createCachedCatalog(identity, cache, catalog) {
+    const plain = catalog ?? createCatalog(identity);
+    const http = identity;
+    const resource = createResourceFactory(cache, http);
+    const resources = {
+        products: {
+            search: (input) => resource('products.search', undefined, input, (o) => plain.products.search(input, o)),
+            getBySlug: (variantSlug, input) => {
+                named('a variant slug', variantSlug);
+                return resource('products.getBySlug', variantSlug, input, (o) => plain.products.getBySlug(variantSlug, input, o));
+            },
+            getById: (id, input) => {
+                named('an id', id);
+                return resource('products.getById', id, input, (o) => plain.products.getById(id, input, o));
+            },
+            getReviews: (id, input) => {
+                named('an id', id);
+                // Nothing asked and an empty ask are the same question
+                return resource('products.getReviews', id, input ?? {}, (o) => plain.products.getReviews(id, input, o));
+            },
+            getRelated: (id, input) => {
+                named('an id', id);
+                return resource('products.getRelated', id, input, (o) => plain.products.getRelated(id, input, o));
+            },
+        },
+        storeData: {
+            get: (input) => resource('storeData.get', undefined, input ?? {}, (o) => plain.storeData.get(input, o)),
+        },
+    };
+    return {
+        resource: resources,
+        products: {
+            search: (input, options) => resources.products.search(input).load(options),
+            getBySlug: (variantSlug, input, options) => resources.products.getBySlug(variantSlug, input).load(options),
+            getById: (id, input, options) => resources.products.getById(id, input).load(options),
+            getReviews: (id, input, options) => resources.products.getReviews(id, input).load(options),
+            getRelated: (id, input, options) => resources.products.getRelated(id, input).load(options),
+        },
+        storeData: {
+            get: (input, options) => resources.storeData.get(input).load(options),
+        },
+        invalidate(target) {
+            const store = { base: http.baseUrl, storeId: http.storeId };
+            cache.invalidate(target ? cachePrefix({ ...store, call: target.call, subject: 'subject' in target ? target.subject : undefined }) : cachePrefix(store));
+        },
+    };
+}
+//# sourceMappingURL=cached.js.map

package/dist/catalog/catalog.d.ts

@@ -0,0 +1,10 @@
+import type { HttpClient } from '../http.js';
+import { type ProductsApi } from './products.js';
+import { type StoreDataApi } from './store-data.js';
+export interface Catalog {
+    products: ProductsApi;
+    storeData: StoreDataApi;
+}
+/** The catalog's calls, over a client made for the catalog's address (`createHttpClient`). Each call answers what the catalog answers. */
+export declare function createCatalog(http: HttpClient): Catalog;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog/catalog.js

@@ -0,0 +1,7 @@
+import { createProductsApi } from './products.js';
+import { createStoreDataApi } from './store-data.js';
+/** The catalog's calls, over a client made for the catalog's address (`createHttpClient`). Each call answers what the catalog answers. */
+export function createCatalog(http) {
+    return { products: createProductsApi(http), storeData: createStoreDataApi(http) };
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog/named.d.ts

@@ -0,0 +1,3 @@
+/** What names one thing in an address (a product's id, a variant's slug) must be something: an empty one would be the address of the list, and ask for a search with the wrong body. */
+export declare function named(what: string, value: string): string;
+//# sourceMappingURL=named.d.ts.map

package/dist/catalog/named.js

@@ -0,0 +1,7 @@
+/** What names one thing in an address (a product's id, a variant's slug) must be something: an empty one would be the address of the list, and ask for a search with the wrong body. */
+export function named(what, value) {
+    if (typeof value !== 'string' || value === '')
+        throw new TypeError(`${what} is needed to ask for a product`);
+    return encodeURIComponent(value);
+}
+//# sourceMappingURL=named.js.map

package/dist/catalog/products.d.ts

@@ -0,0 +1,28 @@
+import type { HttpClient } from '../http.js';
+import type { CallOptions, ProductByIdInput, ProductBySlugInput, ProductDetailResponse, ProductPage, ProductRelatedInput, ProductReviewsInput, ProductSearch, ReviewPage } from './types.js';
+export interface ProductsApi {
+    /**
+     * `POST /public/products`: the store's products, filtered, sorted and paginated as asked. Nothing is added to what is asked (no page, no limit, no sorting): the server's own
+     * defaults apply to what is left out. The body goes out in its canonical form (keys and lists in order), so the same search is always the same request.
+     */
+    search(input: ProductSearch, options?: CallOptions): Promise<ProductPage>;
+    /**
+     * `POST /public/products/by-slug/{variantSlug}`: the product that has a variant with this slug, with all it has. A product has no slug: it is the VARIANT's. What is loaded with it is for
+     * `input`'s `include*` to say.
+     */
+    getBySlug(variantSlug: string, input: ProductBySlugInput, options?: CallOptions): Promise<ProductDetailResponse>;
+    /** `POST /public/products/{id}`: the product with this id, with all it has. */
+    getById(id: string, input: ProductByIdInput, options?: CallOptions): Promise<ProductDetailResponse>;
+    /**
+     * `POST /public/products/{id}/reviews`: the product's reviews, a page of them, with how many there are for each grade. The id is the product's (a UUID: the catalog refuses anything else with a 400).
+     * A product with no reviews is an empty page, not an error.
+     */
+    getReviews(id: string, input?: ProductReviewsInput, options?: CallOptions): Promise<ReviewPage>;
+    /**
+     * `POST /public/products/{id}/related`: the products related to this one (up to ten, the most relevant first), in the same shape as a search's. The id is the product's (a UUID).
+     * A product with nothing related is an empty page, not an error.
+     */
+    getRelated(id: string, input: ProductRelatedInput, options?: CallOptions): Promise<ProductPage>;
+}
+export declare function createProductsApi(http: HttpClient): ProductsApi;
+//# sourceMappingURL=products.d.ts.map

package/dist/catalog/products.js

@@ -0,0 +1,12 @@
+import { canonicalize } from '../canonical.js';
+import { named } from './named.js';
+export function createProductsApi(http) {
+    return {
+        search: (input, options) => http.request({ method: 'POST', path: '/public/products', body: canonicalize(input), signal: options?.signal }),
+        getBySlug: (variantSlug, input, options) => http.request({ method: 'POST', path: `/public/products/by-slug/${named('a variant slug', variantSlug)}`, body: canonicalize(input), signal: options?.signal }),
+        getById: (id, input, options) => http.request({ method: 'POST', path: `/public/products/${named('an id', id)}`, body: canonicalize(input), signal: options?.signal }),
+        getRelated: (id, input, options) => http.request({ method: 'POST', path: `/public/products/${named('an id', id)}/related`, body: canonicalize(input), signal: options?.signal }),
+        getReviews: (id, input, options) => http.request({ method: 'POST', path: `/public/products/${named('an id', id)}/reviews`, body: canonicalize(input ?? {}), signal: options?.signal }),
+    };
+}
+//# sourceMappingURL=products.js.map

package/dist/catalog/store-data.d.ts

@@ -0,0 +1,13 @@
+import type { HttpClient } from '../http.js';
+import type { CallOptions, StoreDataResponse } from './types.js';
+export interface StoreDataApi {
+    /**
+     * `GET /public/store_data`: what the store is made of for a customer: its settings, the collections, the filters, the tags and the attributes to filter and sort by. The answer is
+     * the catalog's own (`{ data: … }`), unchanged. `langCode` is the language the names come in: `default` (or none) is the store's default language, and one the store does not use gets it too.
+     */
+    get(input?: {
+        langCode?: string;
+    }, options?: CallOptions): Promise<StoreDataResponse>;
+}
+export declare function createStoreDataApi(http: HttpClient): StoreDataApi;
+//# sourceMappingURL=store-data.d.ts.map

package/dist/catalog/store-data.js

@@ -0,0 +1,6 @@
+export function createStoreDataApi(http) {
+    return {
+        get: (input, options) => http.request({ path: '/public/store_data', query: { langCode: input?.langCode }, signal: options?.signal }),
+    };
+}
+//# sourceMappingURL=store-data.js.map