@estoreclub/api 0.0.0-stage → 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,407 @@
+import type { AddCartItemParams, CreateCheckoutParams, GetCartParams, GetCheckoutParams, TrackOrderParams, GetCategoryParams, ListCategoriesParams, ListProductsParams, Paginated, PublicCart, PublicCheckout, PublicCheckoutSession, PublicCategory, PublicCompany, GetDictionaryParams, GetProductParams, ListCombosParams, PublicCombo, PublicDiscountRule, PublicDictionary, PublicImage, PublicDictionarySummary, PublicStoreLocation, PublicTerms, PublicProduct, PublicProductSettingDefinition, PublicSiteInfo, RemoveCartItemParams, SetCartBookingParams, SetCartItemQuantityParams, SetCheckoutEmailParams, CreateBookingParams, GetBookingPlanParams, GetBookingSlotsParams, GetOrderTimesParams, PublicBooking, CustomerTokenParams, PublicCustomer, PublicCustomerAccount, PublicCustomerBooking, PublicBookingPreorder, SetBookingPreorderParams, PublicCustomerOrder, PublicCustomerOrderDetail, PublicCustomerSession, CustomerPage, CustomerHistoryParams, CustomerBookingsParams, AddCustomerAddressParams, PublicCustomerAddress, PublicCustomerPaymentMethod, CreateProductCommentParams, DeleteProductCommentParams, GetProductCommentsParams, GetProductFeedbackParams, PublicProductComment, PublicProductCommentsPage, PublicProductFeedback, PublicCommentVoteResult, PublicProductRating, RateProductParams, UnrateProductParams, VoteProductCommentParams, RequestSignInCodeParams, SignInWithAppleParams, SignInWithGoogleParams, RefreshCustomerTokenParams, UpdateCustomerProfileParams, VerifySignInCodeParams, PublicBookingPlan, PublicBookingSlots, PublicOrderTimes, PublicDiningTable } from "./types";
+export interface PublicApiConfig {
+    /** e.g. `http://localhost:4000` — the value of `NEXT_PUBLIC_SERVER_URL`. */
+    baseUrl: string;
+    /**
+     * The COMPANY's own key, and the only credential this client knows.
+     *
+     * It goes on the wire as `x-company-api-key`, which every public route authenticates with —
+     * and the server resolves the company FROM it. That is why there is no domain in this
+     * config: the key already says whose data this is, so there is nothing left for a caller to
+     * choose, and no way to point one company's key at another's catalogue.
+     *
+     * `setCompanyApiKey()` sets the same thing process-wide, for a caller that learns the key
+     * after this client was built; a key given here wins over that one.
+     *
+     * Where it comes from is deliberately somebody else's problem. The TRUSTED layer in front of
+     * a rendered page — the preview's route handler, the public site's server — turns a host or
+     * a deployment id into a company key and hands the page only that. The platform key and the
+     * lookup that uses it never enter this package.
+     */
+    companyApiKey?: string;
+    /**
+     * Read a product SAMPLE instead of the company's own catalogue — its slug, e.g. `sample-pizza`,
+     * the same id a template names as its `productSampleId`. Sent as `x-product-sample`.
+     *
+     * The key still decides whose SITE this is: `getSiteInfo()` answers with the company's own
+     * name, languages and currency. Only the menu changes — products, categories, lists, product
+     * settings, and the cart built from them. A checkout is refused, since nobody sells a sample.
+     */
+    productSample?: string;
+    /**
+     * The visitor a call is made for, sent as `x-visitor-ip` with `platformKey` as `x-api-key`:
+     * the API counts the emails a visitor sets off (sign-in codes, confirmations) by their address,
+     * and a call relayed by a server would otherwise all come from that server. Believed only with
+     * the platform key, so set by the platform's own site server only - never page code.
+     */
+    visitor?: {
+        ip: string;
+        platformKey: string;
+    };
+    /**
+     * How `fetch` may cache. `no-store` unless told otherwise: a page is rendered per request
+     * and a menu, a price or a basket must never be served stale.
+     *
+     * A STATIC EXPORT is the exception — it is rendered once, at build time, and Next refuses a
+     * `no-store` fetch there (the route "couldn't be rendered statically"), which a page catches
+     * as an unavailable API and draws its empty state. The template preview is one.
+     */
+    cache?: RequestCache;
+    /**
+     * The language names and descriptions come back in, sent as `x-language`. Omitted, the one
+     * `setLanguageResolver()` answers with for this request — see `language.ts`. Null: the shop's
+     * default, never the resolver - a client made for one request, whose resolver may be set by
+     * another request's render at the same moment.
+     */
+    language?: string | null;
+    /**
+     * The signed-in customer every call is made as, sent as `x-customer-token` - what a shop
+     * open to signed-in customers only (`customerAccess: signed_in`) needs on its catalogue,
+     * cart and checkout reads too. A call's own `customerToken` wins. Omitted, the one
+     * `setCustomerTokenResolver()` answers with for this render - see `customerToken.ts`. Set by
+     * the trusted layer only, from its cookie: the token never reaches page code. Null: a guest,
+     * never the resolver - a client made for one request (the RPC endpoint), which must not pick
+     * up the token of another visitor's render running at the same moment.
+     */
+    customerToken?: string | null;
+    /**
+     * The country the visitor is in ("NZ"), answered as `getSiteInfo().visitorCountry`. Omitted,
+     * the one `setVisitorCountryResolver()` answers with for this render - see
+     * `visitorCountry.ts`. Null: unknown, never the resolver - a client made for one request.
+     */
+    visitorCountry?: string | null;
+    /** Injected for tests, and for callers with their own fetch wrapper (caching, retries). */
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * The public API, bound to one company by its key.
+ *
+ * Every method here maps to a route that exists. A page list is not among them, so it is
+ * absent rather than stubbed.
+ *
+ * The listings and single-category read take `include`, the optional parts of each row. The
+ * API sends none of them unless asked; this client asks for ALL of them unless the caller
+ * narrows the list — pages written before `include` existed keep rendering images and
+ * settings, and a page that wants a lighter response says which parts it needs.
+ */
+export interface PublicApiClient {
+    /** The company the key belongs to, minus the key itself. */
+    getCompany(): Promise<PublicCompany>;
+    /** The same record as a *site*: what a page renders in its header and its `<head>`. */
+    getSiteInfo(): Promise<PublicSiteInfo>;
+    /**
+     * Active categories, in the order the author arranged them. A plain array — this route is
+     * not paginated, so `limit` is applied to the answer rather than to the request.
+     */
+    getCategories(params?: ListCategoriesParams): Promise<PublicCategory[]>;
+    /** One category by `id`, or by what it is CALLED. See `GetCategoryParams`. */
+    getCategory(params: GetCategoryParams): Promise<PublicCategory>;
+    /** Active products. PAGINATED — the list is under `.data`, unlike categories. */
+    getProducts(params?: ListProductsParams): Promise<Paginated<PublicProduct>>;
+    /**
+     * One product by `id`, or by what it is called — the counterpart of `getCategory`.
+     *
+     * A page written by hand can say "Pizza Margherita"; a page holding a row from a listing
+     * passes its `id`. Always carries every part — the same settings, media and prices as a
+     * full listing row.
+     */
+    getProduct(params: GetProductParams): Promise<PublicProduct>;
+    /**
+     * The shop's own settings CATALOGUE: which fields it keeps on a product, what kind of value
+     * each holds, and which of them it shows. A plain array — the response wraps it in
+     * `{ settings }` and this unwraps it, the way `getCategories` flattens its own answer.
+     *
+     * For one product's values, read `product.settings`: the same keys, described, with what
+     * that product holds.
+     *
+     * Only the fields the shop has switched on and lets websites read: a field it keeps private
+     * (a SKU, a cost, a supplier) is in neither answer.
+     */
+    getProductSettings(params?: {
+        /** Only the yes/no fields — the same set `getProducts({ tags })` filters against. */
+        tagsOnly?: boolean;
+    }): Promise<PublicProductSettingDefinition[]>;
+    /**
+     * Every list the shop can read — its own, then the platform's (currencies, languages) —
+     * with the columns their entries carry, but not the entries. Find a list here, read its
+     * entries with `getDictionary({ identifier })`.
+     *
+     * Only the lists the shop marked "Visible on site" in the admin; a list it keeps private is
+     * not here, and a column it keeps private is left out of every list.
+     */
+    listDictionaries(): Promise<PublicDictionarySummary[]>;
+    /**
+     * The shop's locations, in its own order — for a "find us" list or a map. Not split by
+     * workspace: a location is a place. Empty for a shop that has entered none.
+     */
+    getLocations(): Promise<PublicStoreLocation[]>;
+    /** A table a guest is ordering from, by the id on its QR code: its name, and whether it is open. */
+    getDiningTable(params: {
+        tableId: string;
+    }): Promise<PublicDiningTable>;
+    /** Checks the code staff gave a guest at this table; rejects a wrong one. Books nothing. */
+    verifyDiningTableCode(params: {
+        tableId: string;
+        code: string;
+    }): Promise<void>;
+    /**
+     * The shop's terms and privacy policy - whether customers must accept them, and the text it
+     * wrote (Markdown) in the visitor's language. Shown at sign-up and to a signed-in customer
+     * with `terms` among their `missingFields`; accepted with `acceptTerms: true` on their account.
+     */
+    getTerms(params?: {
+        language?: string;
+    }): Promise<PublicTerms>;
+    /**
+     * The times a party can book on a day at one location — every half hour it is open, each
+     * saying whether a table that seats them is free. Refused while the shop takes no bookings
+     * (`getSiteInfo().reservationMode` not `off`).
+     */
+    getBookingSlots(params: GetBookingSlotsParams): Promise<PublicBookingSlots>;
+    /**
+     * When an order can be for — now, and the later times on the location's clock. Empty `days`
+     * when the shop does not let customers choose a time.
+     */
+    getOrderTimes(params?: GetOrderTimesParams): Promise<PublicOrderTimes>;
+    /** The location's floor plan at a time: what to draw, which tables are free, the best fit. */
+    getBookingPlan(params: GetBookingPlanParams): Promise<PublicBookingPlan>;
+    /**
+     * Book a table — confirmed at once. Refused (409) when no table is free any more; pick
+     * another time.
+     */
+    createBooking(params: CreateBookingParams): Promise<PublicBooking>;
+    /**
+     * Emails the visitor a six-digit sign-in code — only while `customerSignInMethods.email`.
+     * There is no separate sign-up: an email the shop does not know becomes a
+     * customer. Refused (429) when a code went to that email under two minutes ago.
+     */
+    requestSignInCode(params: RequestSignInCodeParams): Promise<{
+        expiresIn: number;
+    }>;
+    /**
+     * Signs in with the emailed code. Keep the `token` it answers with where only the site's
+     * server can read it (an httpOnly cookie), and pass it as `customerToken`.
+     */
+    verifySignInCode(params: VerifySignInCodeParams): Promise<PublicCustomerSession>;
+    /** Signs in with the ID token Google Identity Services gave the page. */
+    signInWithGoogle(params: SignInWithGoogleParams): Promise<PublicCustomerSession>;
+    /**
+     * Signs in with the ID token the platform's Apple popup posted back, and the name Apple sent
+     * beside it (the first sign-in only).
+     */
+    signInWithApple(params: SignInWithAppleParams): Promise<PublicCustomerSession>;
+    /**
+     * Trades a refresh token for a new session — a new `token` AND a new `refreshToken`; the one
+     * sent is spent. 401 when it is unknown, run out, spent, or for another shop: sign out.
+     * Server side only, like the sign-ins: neither token may reach the browser.
+     */
+    refreshCustomerToken(params: RefreshCustomerTokenParams): Promise<PublicCustomerSession>;
+    /** Ends the session the refresh token belongs to. Quiet for one already gone. */
+    signOutCustomer(params: RefreshCustomerTokenParams): Promise<void>;
+    /** The signed-in customer, with their recent orders and bookings. 401 when the token lapsed. */
+    getCustomerAccount(params: CustomerTokenParams): Promise<PublicCustomerAccount>;
+    /** The signed-in customer's orders on this site, newest first. */
+    getCustomerOrders(params: CustomerTokenParams & CustomerHistoryParams): Promise<CustomerPage<PublicCustomerOrder>>;
+    /** One of their orders, with its lines. Rejects (404) for an order that is not theirs. */
+    getCustomerOrder(params: CustomerTokenParams & {
+        orderId: string;
+    }): Promise<PublicCustomerOrderDetail>;
+    /** Their bookings — upcoming by default. */
+    getCustomerBookings(params: CustomerTokenParams & CustomerBookingsParams): Promise<CustomerPage<PublicCustomerBooking>>;
+    /**
+     * Calls off one of their bookings — only while it is still ahead and not yet seated. Answers
+     * with the booking, now `cancelled`.
+     */
+    cancelCustomerBooking(params: CustomerTokenParams & {
+        /** The booking - its `bookingNumber` (`12`) or its `bookingId`. */
+        bookingId: string | number;
+    }): Promise<PublicCustomerBooking>;
+    /**
+     * Sets the dishes they order ahead for one of their bookings - every dish and how many,
+     * replacing what was there; empty takes the preorder away. Kept as the booking's unpaid order,
+     * paid at the table. Refused once the booking is no longer theirs to change
+     * (`cancellableUntil`). Answers with the preorder as kept, or null.
+     */
+    setCustomerBookingPreorder(params: SetBookingPreorderParams): Promise<{
+        preorder: PublicBookingPreorder | null;
+    }>;
+    /** The places they have had orders delivered to, or saved - the one used last first. */
+    getCustomerAddresses(params: CustomerTokenParams): Promise<{
+        data: PublicCustomerAddress[];
+    }>;
+    /** Saves an address for them; the same one again only moves its `lastUsedAt`. */
+    addCustomerAddress(params: AddCustomerAddressParams): Promise<PublicCustomerAddress>;
+    /** Forgets one of their addresses. */
+    deleteCustomerAddress(params: CustomerTokenParams & {
+        customerAddressId: string;
+    }): Promise<void>;
+    /** The cards they saved paying here - brand, last four, expiry; nothing that can pay. */
+    getCustomerPaymentMethods(params: CustomerTokenParams): Promise<{
+        data: PublicCustomerPaymentMethod[];
+    }>;
+    /** Removes one of their saved cards. Refused (409) for one an upcoming booking keeps. */
+    deleteCustomerPaymentMethod(params: CustomerTokenParams & {
+        paymentMethodId: string;
+    }): Promise<void>;
+    /**
+     * Their favourite products, as `getProducts` lists them - the same paging, `include` and
+     * filters, limited to the ones they added.
+     */
+    getCustomerFavourites(params: CustomerTokenParams & ListProductsParams): Promise<Paginated<PublicProduct>>;
+    /** Just their favourites' ids, newest first - to fill in the hearts on a listing. */
+    getCustomerFavouriteIds(params: CustomerTokenParams): Promise<{
+        productIds: string[];
+    }>;
+    /** Adds a product to their favourites; one already there stays once. */
+    addCustomerFavourite(params: CustomerTokenParams & {
+        productId: string;
+    }): Promise<void>;
+    /** Takes a product out of their favourites; one not there is no error. */
+    removeCustomerFavourite(params: CustomerTokenParams & {
+        productId: string;
+    }): Promise<void>;
+    /** Changes the signed-in customer's name or phone; their email stays. */
+    updateCustomerProfile(params: UpdateCustomerProfileParams): Promise<PublicCustomer>;
+    /**
+     * What a product takes — comments, stars, likes — and its totals. Any visitor may read it;
+     * pass `customerToken` for the signed-in customer's own stars.
+     */
+    getProductFeedback(params: GetProductFeedbackParams): Promise<PublicProductFeedback>;
+    /**
+     * A product's comments, newest first — roots only, each with its `replyCount`. With
+     * `parentId`, that root's replies, oldest first. Empty when the product takes no comments.
+     */
+    getProductComments(params: GetProductCommentsParams): Promise<PublicProductCommentsPage>;
+    /**
+     * Comments on a product as the signed-in customer, or replies with `parentId`. 403 when the
+     * product takes no comments (`getProductFeedback().allowComments`).
+     */
+    createProductComment(params: CreateProductCommentParams): Promise<PublicProductComment>;
+    /** Removes one of the signed-in customer's own comments; a root goes with its replies. */
+    deleteProductComment(params: DeleteProductCommentParams): Promise<void>;
+    /**
+     * The signed-in customer's vote on a product, the shop's way (`productVoting`): stars or a
+     * like / dislike. A new one replaces theirs. Answers with the product's votes. 403 when the
+     * product takes none, 400 for a vote the other way.
+     */
+    rateProduct(params: RateProductParams): Promise<PublicProductRating>;
+    /** Takes the signed-in customer's vote on a product back. */
+    unrateProduct(params: UnrateProductParams): Promise<PublicProductRating>;
+    /**
+     * The signed-in customer's vote on a comment, the shop's way (`commentVoting`); 0 takes it
+     * back. Answers with the comment's votes.
+     */
+    voteProductComment(params: VoteProductCommentParams): Promise<PublicCommentVoteResult>;
+    /**
+     * The combos on sale NOW — active, inside their dates and inside one of their weekly windows
+     * at the moment of the request — in the shop's order, each with its slots and the products
+     * that may fill them. Pass `categoryId` for the ones the shop displays in that category.
+     */
+    getCombos(params?: ListCombosParams): Promise<PublicCombo[]>;
+    /**
+     * The discount rules on now, for badging the products they target. Display only: the cart
+     * decides which rule a unit actually takes.
+     */
+    getDiscountRules(): Promise<PublicDiscountRule[]>;
+    /**
+     * One of the shop's own lists, by `identifier`, by `id` or by name — its sizes, its add-ons,
+     * its ingredients.
+     *
+     * `identifier` is the handle the shop gave the list (`"add_ons"`): set once, never changed,
+     * and shown on the list's own page in the admin. Write pages against it — the label is
+     * translated and reworded, so a page reading by name breaks when the shop renames the list.
+     *
+     * What a product carries is the NAMES it uses out of a list; this is the list itself, with
+     * the columns each entry holds. A page that prices an add-on reads it here, because the
+     * surcharge is a fact about the entry rather than about any product offering it.
+     *
+     * A list the shop keeps private (not "Visible on site") answers 404 exactly like a missing
+     * one, and a private column is left out of `columns` and of every entry's `values`.
+     */
+    getDictionary(params: GetDictionaryParams): Promise<PublicDictionary>;
+    /**
+     * Several lists in ONE request, by identifier — the batch form of `getDictionary`.
+     *
+     * A page that needs many lists (a menu's sizes, add-ons, bases, …) reads them all in a single
+     * round trip instead of one each. The answer is the lists that exist, each carrying its own
+     * `identifier` to match back against what was asked; an identifier with no list is simply
+     * absent (not an error), so map by `identifier` rather than by position. A private list is
+     * absent the same way.
+     */
+    getDictionaries(params: {
+        identifiers: string[];
+    }): Promise<PublicDictionary[]>;
+    /**
+     * Size and resized copies of pictures the site holds only as URLs — a "Site images" entry, a
+     * size's drawing, a location photo — so `Image` can serve them like a product's photos.
+     *
+     * Answers only for the shop's own media and the platform's shared images that have copies;
+     * any other URL is left out, and is drawn from the URL as it is. At most 200 per call.
+     */
+    lookupImages(params: {
+        urls: string[];
+    }): Promise<PublicImage[]>;
+    /**
+     * The basket, held by the server so it survives a reload.
+     *
+     * `createCart` first; everything after it needs the `cartId` that returns. The server also
+     * sets that id as a cookie, so a browser on the same site can omit it — but this client
+     * passes it explicitly whenever it has one, because a server component has no cookie jar and
+     * because an explicit id cannot be silently swapped by whatever the jar happens to hold.
+     *
+     * Every call answers with the WHOLE cart, so a caller never has to reconstruct it from a
+     * response describing only what changed.
+     */
+    createCart(): Promise<PublicCart>;
+    getCart(params: GetCartParams): Promise<PublicCart>;
+    /** Adds, or increases a line already there — lines are (product, variantId, variant). */
+    addCartItem(params: AddCartItemParams): Promise<PublicCart>;
+    /** Zero removes the line, so a stepper needs no second call. */
+    setCartItemQuantity(params: SetCartItemQuantityParams): Promise<PublicCart>;
+    removeCartItem(params: RemoveCartItemParams): Promise<PublicCart>;
+    /** Say which table booking the basket is ordered for - or none. */
+    setCartBooking(params: SetCartBookingParams): Promise<PublicCart>;
+    destroyCart(params: GetCartParams): Promise<void>;
+    /**
+     * Turn the basket into a checkout, and get the page that takes the payment.
+     *
+     * The answer's `checkoutUrl` is where the SHOPPER goes — redirect their browser to it. The
+     * page asks for their email unless `customerEmail` was given, shows the order, takes the card
+     * (saving it only if they choose), and sends them back to `successUrl` once paid. The cart moves to `checkout` now, and to `paid` when Stripe
+     * confirms.
+     */
+    createCheckout(params: CreateCheckoutParams): Promise<PublicCheckout>;
+    /**
+     * Read a checkout — including what is needed to take the card in the page itself.
+     *
+     * The id is the credential, exactly as a cart id is: the route takes no key, because the
+     * page that charges may be a browser. While the checkout can still be paid the answer
+     * carries `payment`, which Stripe's Elements mount against; once it is paid or cancelled
+     * that is gone and `status` is the answer.
+     */
+    getCheckout(params: GetCheckoutParams): Promise<PublicCheckoutSession>;
+    /**
+     * Record who is paying, from the site's own payment page — the receipt goes there, and it is
+     * how a card they saved at this shop is offered again. Answers with the checkout as
+     * `getCheckout` would, its `payment` now carrying `customerSessionClientSecret`. Like
+     * `getCheckout`, the id is the credential; refused once the checkout can no longer be paid.
+     */
+    setCheckoutEmail(params: SetCheckoutEmailParams): Promise<PublicCheckoutSession>;
+    /**
+     * Find a placed order for the shop's tracking page - signed in or not: its `number` (`1042`,
+     * `#1042`, or the delivery's `D-17`) with the `email` it was placed with, or `checkoutId`
+     * alone. Answers as `getCustomerOrder` does, with `shipment` once a carrier has it. Every
+     * mismatch is the same 404 (`order_track_not_found`); limited per visitor (429). Never cached.
+     */
+    trackOrder(params: TrackOrderParams): Promise<PublicCustomerOrderDetail>;
+}
+/**
+ * Build a client.
+ *
+ * Whose data it reads is decided entirely by the key, and that is the whole design. A client
+ * that took a domain per call would let whoever held one read any company; a client that took
+ * one at construction still made every caller carry a value the server does not read. Neither
+ * is here any more.
+ */
+export declare function createPublicApiClient(config: PublicApiConfig): PublicApiClient;

package/dist/client.js

@@ -0,0 +1,14 @@
+import {
+  createPublicApiClient
+} from "./chunks/chunk-5DN7L6LX.js";
+import "./chunks/chunk-2BH4QPV2.js";
+import "./chunks/chunk-2554RPSS.js";
+import "./chunks/chunk-TSERNR4R.js";
+import "./chunks/chunk-OFFTL6RC.js";
+import "./chunks/chunk-GJZ7EZEF.js";
+import "./chunks/chunk-HFEQWXG6.js";
+import "./chunks/chunk-3KEEGSMP.js";
+export {
+  createPublicApiClient
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/companyApiKey.d.ts

@@ -0,0 +1,9 @@
+/** Set it, or pass null/empty to fall back to the config and the environment. */
+export declare function setCompanyApiKey(key: string | null | undefined): void;
+/**
+ * What is currently set, or null.
+ *
+ * Returns the key itself, so treat it as the secret it is: it belongs in a request header,
+ * never in a log line, an error message or anything a page renders.
+ */
+export declare function getCompanyApiKey(): string | null;

package/dist/companyApiKey.js

@@ -0,0 +1,9 @@
+import {
+  getCompanyApiKey,
+  setCompanyApiKey
+} from "./chunks/chunk-TSERNR4R.js";
+export {
+  getCompanyApiKey,
+  setCompanyApiKey
+};
+//# sourceMappingURL=companyApiKey.js.map

package/dist/companyApiKey.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/customerToken.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The signed-in customer a render is made for, for every call it makes.
+ *
+ * A shop may show itself to signed-in customers only (`customerAccess: signed_in`): the API then
+ * refuses a guest its catalogue, cart, checkout and bookings. A page's reads are made on the
+ * server, which knows the visitor only by the request's cookie - so the render tier reads the
+ * token from that cookie and sets a resolver here for the length of one render, the same way it
+ * sets the language (`language.ts`). Every call then carries `x-customer-token` without page
+ * code passing anything - page code never sees the token.
+ *
+ * A call that names its own `customerToken` keeps it; nothing set here means a guest's calls.
+ */
+export type CustomerTokenResolver = () => string | null | undefined;
+export declare function setCustomerTokenResolver(next: CustomerTokenResolver | null): void;
+/** The resolver in force, so the render tier can put back exactly what was there. */
+export declare function getCustomerTokenResolver(): CustomerTokenResolver | null;
+/** The token to send, or undefined for a guest. Never throws. */
+export declare function resolveCustomerToken(): string | undefined;

package/dist/customerToken.js

@@ -0,0 +1,11 @@
+import {
+  getCustomerTokenResolver,
+  resolveCustomerToken,
+  setCustomerTokenResolver
+} from "./chunks/chunk-OFFTL6RC.js";
+export {
+  getCustomerTokenResolver,
+  resolveCustomerToken,
+  setCustomerTokenResolver
+};
+//# sourceMappingURL=customerToken.js.map

package/dist/customerToken.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * One error type, and deliberately uninformative.
+ *
+ * The message can end up rendered by a page — the runtime hands it straight to page code as
+ * the reason a capability failed — so it names a status and nothing else. The internal URL,
+ * the base host and the key are exactly what must not travel with it.
+ */
+/** What a refusal says beyond its status and sentence - see `PublicApiError`. */
+export interface RefusalFacts {
+    code?: string;
+    missingFields?: string[];
+}
+/** The refusal facts in an API answer's body (or a relayed error), keeping only well-formed ones. */
+export declare function refusalFactsOf(body: unknown): RefusalFacts;
+export declare class PublicApiError extends Error {
+    readonly status?: number;
+    /**
+     * What the SERVER said, when it said anything.
+     *
+     * Kept apart from `message`, which stays terse and safe to render anywhere. This is the
+     * server's own sentence — "Amount must convert to at least 50 cents", "One or more products
+     * not found" — and it is the only part that tells a caller what to do differently. Without
+     * it a page could say nothing better than "that did not work", while the reason sat in a
+     * log nobody was reading.
+     *
+     * Shown at the CALLER's discretion, because only the caller knows who is reading. A shop's
+     * own admin screen can print it; a page facing a shopper should decide case by case.
+     */
+    readonly detail?: string;
+    /**
+     * The refusal's machine-readable `code` (`customer_sign_in_required`, `customer_details_required`),
+     * when the API gave one - what a page branches on, unlike the sentence in `detail`.
+     */
+    readonly code?: string;
+    /**
+     * The details a signed-in customer still owes, with `customer_details_required` - so a page asks
+     * for exactly those without reading the account first.
+     */
+    readonly missingFields?: string[];
+    constructor(reason: string, status?: number, detail?: string, refusal?: RefusalFacts);
+}

package/dist/errors.js

@@ -0,0 +1,9 @@
+import {
+  PublicApiError,
+  refusalFactsOf
+} from "./chunks/chunk-GJZ7EZEF.js";
+export {
+  PublicApiError,
+  refusalFactsOf
+};
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `@estoreclub/api` — the client for the server's PUBLIC company API.
+ *
+ * One place knows how a site's data becomes an HTTP request: the URLs, the key header, the
+ * timeout, the paging clamp. Everything else asks this.
+ *
+ * Two ways in, on purpose:
+ *
+ *  - **`getSiteInfo` / `getCategories` / `getCategory` / `getProducts` / `getProduct` /
+ *    `listDictionaries` / `getDictionary`** — the site's own data,
+ *    read through a client configured once from the environment. This is what PAGE CODE
+ *    imports, and it is server-only: `COMPANY_API_KEY` is a secret.
+ *  - **`createPublicApiClient`** — the client itself, for a caller that gets the key from
+ *    something other than the environment (a request, a test, a tool reading several sites).
+ *
+ * It is deliberately small and dependency-free — one `fetch`, no framework, no React, no node
+ * builtins — so it runs in a Next server component, a script and a test alike.
+ *
+ * **It knows nothing about domains.** Every public route authenticates with
+ * `x-company-api-key` and the server resolves the company from that key, so the key IS the
+ * answer to whose data is read. Turning a host or a deployment id into one is the job of the
+ * trusted layer in front of the page, which holds the platform key; page code supplies
+ * parameters and nothing else — never a domain, never a URL, never a key.
+ */
+export { createPublicApiClient, type PublicApiClient, type PublicApiConfig, } from "./client";
+export { getSiteInfo, getCategories, getCategory, getProducts, getProduct, listDictionaries, getDictionary, getDictionaries, lookupImages, getLocations, getDiningTable, verifyDiningTableCode, getTerms, getBookingSlots, getBookingPlan, getOrderTimes, createBooking, getProductSettings, getCombos, getDiscountRules, resetSiteData, } from "./siteData";
+/**
+ * The basket, held by the server so it survives a reload.
+ *
+ * `createCart()` answers with an id that every other call needs, and that id is the credential
+ * for the cart: keep it out of URLs and out of anything a page renders.
+ */
+export { createCart, getCart, addCartItem, setCartItemQuantity, removeCartItem, setCartBooking, destroyCart, } from "./siteData";
+/**
+ * Paying for the basket, either way round.
+ *
+ * `createCheckout` answers with `checkoutUrl` — the hosted payment page the shopper's browser
+ * is sent to; the platform takes the card and returns them to the site. A site that would
+ * rather keep the shopper on its own page passes that same checkout's id to `getCheckout` and
+ * mounts Stripe's Elements on what comes back; `setCheckoutEmail` records the shopper there.
+ */
+export { createCheckout, getCheckout, setCheckoutEmail } from "./siteData";
+/**
+ * The shop's order-tracking page, signed in or not: an order number (or delivery's `D-17`) with
+ * the email it was placed with, or a checkout id alone, answers with the order and its shipment.
+ */
+export { trackOrder } from "./siteData";
+/**
+ * Customers signing in on the site, the ways the shop allows (`getSiteInfo().customerSignInMethods`).
+ * A sign-in answers with a token; pass it as `customerToken` and what is made with it — a
+ * checkout, a booking — belongs to the customer. Keep it in an httpOnly cookie, server side.
+ */
+export { requestSignInCode, verifySignInCode, signInWithGoogle, signInWithApple, getCustomerAccount, getCustomerOrders, getCustomerOrder, getCustomerBookings, cancelCustomerBooking, setCustomerBookingPreorder, getCustomerAddresses, addCustomerAddress, deleteCustomerAddress, getCustomerPaymentMethods, deleteCustomerPaymentMethod, getCustomerFavourites, getCustomerFavouriteIds, addCustomerFavourite, removeCustomerFavourite, updateCustomerProfile, } from "./siteData";
+/**
+ * What customers say about a product: the switches and totals, its comments and their replies.
+ * Reads take an optional `customerToken` (for `mine`); a comment needs one.
+ */
+export { getProductFeedback, getProductComments, createProductComment, deleteProductComment, rateProduct, unrateProduct, voteProductComment, } from "./siteData";
+/**
+ * The key every scoped call authenticates with, for the whole process. Set by the trusted
+ * layer once it has done the exchange — see `companyApiKey.ts`.
+ */
+export { setCompanyApiKey, getCompanyApiKey } from "./companyApiKey";
+/**
+ * Which language the reads answer in, asked per request — see `language.ts`. Set by the site
+ * once, like the key.
+ */
+export { setLanguageResolver, getLanguageResolver, type LanguageResolver, } from "./language";
+/**
+ * Who the render is made for - the signed-in customer, from the request's cookie - asked per
+ * call. Set by the render tier for one render; see `customerToken.ts`.
+ */
+export { setCustomerTokenResolver, getCustomerTokenResolver, type CustomerTokenResolver, } from "./customerToken";
+/**
+ * The visitor's country, per render - see `visitorCountry.ts`. Set by the render tier from the
+ * request; a page reads it as `getSiteInfo().visitorCountry`.
+ */
+export { setVisitorCountryResolver, getVisitorCountryResolver, countryFromHeaders, type VisitorCountryResolver, } from "./visitorCountry";
+export { PublicApiError } from "./errors";
+export { MAX_LIMIT } from "./params";
+export { runWithRequestCache } from "./requestCache";
+export type { AddCartItemParams, CheckoutStatus, CreateBookingParams, GetBookingPlanParams, GetBookingSlotsParams, ReservationKind, GetOrderTimesParams, PublicBooking, PublicBookingEntry, PublicBookingPlan, PublicBookingSlot, PublicBookingSlots, PublicReservationPayment, ReservationPaymentTiming, PublicOrderTime, PublicOrderTimes, PublicPlanItem, PublicPlanTable, ComboPick, ComboPriceKind, CreateCheckoutParams, CustomerTokenParams, CustomerField, CustomerConsent, CustomerRequiredFields, CurrencySymbolPosition, ByIdOrName, GetCartParams, GetCategoryParams, GetCheckoutParams, TrackOrderParams, GetDictionaryParams, GetProductParams, ListCategoriesParams, ListCombosParams, ListProductsParams, Paginated, PaginationMetadata, DiscountRuleKind, PublicCart, PublicCartCombo, PublicCartComboPick, PublicCartDiscount, PublicCartItem, PublicCombo, PublicComboSlot, PublicComboSlotOption, PublicComboVariant, PublicDealSchedule, PublicDiscountRule, PublicCheckout, PublicCheckoutPayment, PublicCheckoutSession, PublicCategory, PublicCategoryInclude, PublicCustomer, PublicCustomerAccount, PublicCustomerBooking, PublicBookingPreorder, PublicBookingPreorderLine, SetBookingPreorderParams, PublicCustomerAddress, PublicCustomerPaymentMethod, AddCustomerAddressParams, PublicCustomerOrder, PublicCustomerOrderDetail, PublicCustomerOrderLine, PublicCustomerOrderProgress, PublicCustomerOrderShipment, PublicCustomerSession, CustomerPage, CustomerHistoryParams, CustomerBookingsParams, CreateProductCommentParams, DeleteProductCommentParams, GetProductCommentsParams, GetProductFeedbackParams, PublicProductComment, PublicProductCommentsPage, PublicProductFeedback, PublicProductRating, PublicCommentVoteResult, ProductVoting, RateProductParams, UnrateProductParams, VoteProductCommentParams, PublicCompany, PublicDictionary, PublicDictionaryColumn, PublicDictionaryColumnType, PublicDictionaryEntry, PublicDictionarySummary, PublicLanguage, PublicImage, PublicMedia, PublicProduct, PublicProductVariant, PublicProductCategoryRef, PublicProductInclude, ProductSort, PublicProductSetting, PublicProductSettingDefinition, PublicProductSettingRange, PublicProductSettingType, OrderLocationMode, CustomerAccess, OrderType, PublicPaymentDiscount, PublicPaymentDiscounts, PublicSiteInfo, PublicStoreLocation, PublicDiningTable, PublicTerms, RemoveCartItemParams, SetCartBookingParams, RequestSignInCodeParams, SetCartItemQuantityParams, SetCheckoutEmailParams, SignInWithGoogleParams, SignInWithAppleParams, RefreshCustomerTokenParams, UpdateCustomerProfileParams, VerifySignInCodeParams, Workspace, } from "./types";