@skuio/storefront 0.6.1 → 0.7.1

package/README.md

@@ -1,6 +1,6 @@
 # @skuio/storefront
 
-Typed catalogue, checkout and order primitives for storefronts on the SKU.io
+Typed catalog, checkout and order primitives for storefronts on the SKU.io
 storefront kit. Framework-agnostic: takes and returns plain data.
 
 ```ts
@@ -17,7 +17,7 @@ import { createStripeCheckout, parseStripeWebhook } from '@skuio/storefront/stri
   Storefront API: live availability, checkout created by SKU.io on the
   tenant\'s processor, orders born in SKU.io).
 - Stripe helpers behind a separate entry point so non-Stripe stores never
-  bundle it. Prices are only ever read from the catalogue on the server.
+  bundle it. Prices are only ever read from the catalog on the server.
 - Cart functions — pure, browser-agnostic, never trusted for money.
 
 Start a store with `npx @skuio/cli create my-store`. Kit and docs:

package/db/migrations/0008_quotes.sql

@@ -0,0 +1,59 @@
+-- Quotes (request for quote): a buyer — signed in or a guest who never makes an account — asks for a price on a
+-- list of products; the operations system prices it through the Store API; the buyer accepts it, which places an
+-- order at exactly the quoted prices, or declines it. Money is integer minor units; the priced columns stay NULL
+-- until an offer exists.
+CREATE TABLE quotes (
+  id                    TEXT PRIMARY KEY,
+  number                INTEGER NOT NULL UNIQUE,
+  status                TEXT NOT NULL,          -- requested | quoted | accepted | declined | expired | cancelled
+  customer_id           TEXT NOT NULL REFERENCES customers (id),
+  email                 TEXT NOT NULL,
+  company               TEXT NULL,
+  message               TEXT NULL,
+  shipping_address_json TEXT NULL,
+  currency              TEXT NOT NULL,
+  subtotal              INTEGER NULL,
+  shipping              INTEGER NULL,
+  tax                   INTEGER NULL,
+  total                 INTEGER NULL,
+  offer_note            TEXT NULL,
+  expires_at            TEXT NULL,
+  external_reference    TEXT NULL,
+  order_id              TEXT NULL REFERENCES orders (id),
+  decline_reason        TEXT NULL,
+  metadata_json         TEXT NOT NULL DEFAULT '{}',
+  access_key            TEXT NOT NULL,
+  created_at            TEXT NOT NULL,
+  updated_at            TEXT NOT NULL,
+  quoted_at             TEXT NULL,
+  accepted_at           TEXT NULL,
+  declined_at           TEXT NULL,
+  cancelled_at          TEXT NULL
+);
+CREATE INDEX quotes_updated ON quotes (updated_at, id);
+CREATE INDEX quotes_customer ON quotes (customer_id, created_at);
+CREATE INDEX quotes_email ON quotes (email, created_at);
+CREATE INDEX quotes_status ON quotes (status, expires_at);
+
+CREATE TABLE quote_lines (
+  id           TEXT PRIMARY KEY,
+  quote_id     TEXT NOT NULL REFERENCES quotes (id) ON DELETE CASCADE,
+  sku          TEXT NOT NULL,
+  name         TEXT NOT NULL,
+  quantity     INTEGER NOT NULL,
+  list_amount  INTEGER NULL,   -- the catalog price when the buyer asked; for reference only
+  unit_amount  INTEGER NULL,   -- the offered price; NULL until quoted
+  total_amount INTEGER NULL,
+  image_url    TEXT NULL,
+  position     INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX quote_lines_quote ON quote_lines (quote_id, position);
+
+CREATE TABLE quote_events (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  quote_id   TEXT NOT NULL REFERENCES quotes (id) ON DELETE CASCADE,
+  type       TEXT NOT NULL,
+  data_json  TEXT NULL,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX quote_events_quote ON quote_events (quote_id, id);

package/dist/api.d.ts

@@ -1,5 +1,5 @@
 import { CategoryRecord, ProductRecord, Connection, Store } from './store.js';
-import { O as Order, F as Fulfillment } from './config-C4YCi7m4.js';
+import { O as Order, Q as QuoteStatus, F as Fulfillment, S as StoreQuote } from './config-CCxTka_z.js';
 import './driver-Cr4l6GgG.js';
 import './types-CWreCyxc.js';
 
@@ -79,6 +79,48 @@ interface ApiOrder {
     paid_at: string | null;
     cancelled_at: string | null;
 }
+interface ApiQuote {
+    id: string;
+    /** With the store's quote prefix: "Q1001". */
+    number: string;
+    status: QuoteStatus;
+    currency: string;
+    customer: {
+        id: string;
+        email: string;
+        name: string | null;
+        phone: string | null;
+    };
+    company: string | null;
+    message: string | null;
+    shipping_address: ApiAddress | null;
+    lines: {
+        id: string;
+        sku: string;
+        name: string;
+        quantity: number;
+        list_amount: ApiMoney | null;
+        unit_amount: ApiMoney | null;
+        total_amount: ApiMoney | null;
+    }[];
+    subtotal: ApiMoney | null;
+    shipping: ApiMoney | null;
+    tax: ApiMoney | null;
+    total: ApiMoney | null;
+    note: string | null;
+    expires_at: string | null;
+    external_reference: string | null;
+    /** The order the buyer's acceptance placed; it also arrives through GET /orders with `metadata.quote_id`. */
+    order_id: string | null;
+    decline_reason: string | null;
+    metadata: Record<string, string>;
+    created_at: string;
+    updated_at: string;
+    quoted_at: string | null;
+    accepted_at: string | null;
+    declined_at: string | null;
+    cancelled_at: string | null;
+}
 interface ApiProduct {
     sku: string;
     name: string;
@@ -126,8 +168,31 @@ declare function serializeFulfillment(f: Fulfillment): ApiFulfillment;
  * sees, with the store's prefix (VLD4200), so the consumer shows the same number.
  */
 declare function serializeOrder(o: Order, numberPrefix?: string): ApiOrder;
-/** The Store API's view of a catalogue product — the stored row, not the shopper projection. */
-declare function serializeProduct(p: ProductRecord): ApiProduct;
+/** The Store API's view of a quote. `access_key` never leaves the store. */
+declare function serializeQuote(q: StoreQuote, numberPrefix?: string): ApiQuote;
+/**
+ * Maps a stored image src to the public URL a consumer can load. Return null
+ * (or undefined) to fall back to the default: an absolute URL as-is, anything
+ * else resolved against the request origin.
+ */
+type ImageUrlResolver = (src: string) => string | null | undefined;
+interface SerializeProductOptions {
+    /** The store's own image resolver; see StoreApiOptions.imageUrl. */
+    imageUrl?: ImageUrlResolver;
+    /** The origin relative srcs resolve against when the resolver has no answer ("https://store.example"). */
+    origin?: string;
+}
+/**
+ * The absolute URL the Store API reports for an image. The store's resolver
+ * wins; without one (or when it returns null) an absolute URL passes through
+ * unchanged and a relative path or bare filename is resolved against the
+ * request origin. Resolving a bare filename only produces a loadable URL when
+ * the store serves the file at that path — stores that fingerprint their
+ * assets must pass a resolver.
+ */
+declare function absoluteImageUrl(src: string, options?: SerializeProductOptions): string;
+/** The Store API's view of a catalog product — the stored row, not the shopper projection. */
+declare function serializeProduct(p: ProductRecord, options?: SerializeProductOptions): ApiProduct;
 declare function serializeCategory(c: CategoryRecord): ApiCategory;
 
 declare class ValidationError extends Error {
@@ -145,6 +210,15 @@ interface StoreApiOptions {
     apiKey: string | undefined;
     /** Where the API is mounted in the request URL. */
     basePath?: string;
+    /**
+     * Maps a stored product image src (a bare filename, a path, or an absolute
+     * URL) to the absolute URL the store actually serves it at — e.g. the
+     * fingerprinted `/_astro/<name>.<hash>.jpg` a template's `resolveImage()`
+     * finds, made absolute against the site URL. Return null to fall back to the
+     * default: an absolute src as-is, a relative one resolved against the
+     * request origin. `images[].url` in every response is always absolute.
+     */
+    imageUrl?: ImageUrlResolver;
 }
 /** Who a request authenticated as: the environment key, or an approved connection. */
 type ApiCaller = {
@@ -171,7 +245,7 @@ declare function serializeConnection(c: Connection): {
     id: string;
     name: string;
     tenant: string | null;
-    scopes: ("orders" | "payments" | "fulfillments" | "inventory" | "catalog")[];
+    scopes: ("orders" | "payments" | "fulfillments" | "inventory" | "catalog" | "quotes")[];
     key_prefix: string | null;
     created_at: string;
     issued_at: string | null;
@@ -179,4 +253,4 @@ declare function serializeConnection(c: Connection): {
     revoked_at: string | null;
 };
 
-export { type ApiCaller, type ApiCategory, type ApiFulfillment, type ApiOrder, type ApiProduct, STORE_API_BASE, STORE_API_BASES, type StoreApiOptions, ValidationError, handleStoreApi, serializeCategory, serializeConnection, serializeFulfillment, serializeOrder, serializeProduct };
+export { type ApiCaller, type ApiCategory, type ApiFulfillment, type ApiOrder, type ApiProduct, type ApiQuote, type ImageUrlResolver, STORE_API_BASE, STORE_API_BASES, type SerializeProductOptions, type StoreApiOptions, ValidationError, absoluteImageUrl, handleStoreApi, serializeCategory, serializeConnection, serializeFulfillment, serializeOrder, serializeProduct, serializeQuote };

package/dist/api.js

@@ -2,7 +2,7 @@ import {
   API_KEY_PREFIX,
   StoreError,
   secretsEqual
-} from "./chunk-X7VXO4QU.js";
+} from "./chunk-RUUUZ2EL.js";
 
 // src/api/serialize.ts
 var money = (m) => ({ amount: m.amount, currency: m.currency.toUpperCase() });
@@ -64,7 +64,55 @@ function serializeOrder(o, numberPrefix = "") {
     cancelled_at: o.cancelledAt
   };
 }
-function serializeProduct(p) {
+var maybeMoney = (m) => m ? money(m) : null;
+function serializeQuote(q, numberPrefix = "") {
+  return {
+    id: q.id,
+    number: `${numberPrefix}${q.number}`,
+    status: q.status,
+    currency: q.currency.toUpperCase(),
+    customer: { id: q.customer.id, email: q.customer.email, name: q.customer.name, phone: q.customer.phone },
+    company: q.company,
+    message: q.message,
+    shipping_address: address(q.shippingAddress),
+    lines: q.lines.map((l) => ({
+      id: l.id,
+      sku: l.sku,
+      name: l.name,
+      quantity: l.quantity,
+      list_amount: maybeMoney(l.listAmount),
+      unit_amount: maybeMoney(l.unitAmount),
+      total_amount: maybeMoney(l.totalAmount)
+    })),
+    subtotal: maybeMoney(q.subtotal),
+    shipping: maybeMoney(q.shipping),
+    tax: maybeMoney(q.tax),
+    total: maybeMoney(q.total),
+    note: q.offerNote,
+    expires_at: q.expiresAt,
+    external_reference: q.externalReference,
+    order_id: q.orderId,
+    decline_reason: q.declineReason,
+    metadata: q.metadata,
+    created_at: q.createdAt,
+    updated_at: q.updatedAt,
+    quoted_at: q.quotedAt,
+    accepted_at: q.acceptedAt,
+    declined_at: q.declinedAt,
+    cancelled_at: q.cancelledAt
+  };
+}
+var ABSOLUTE = /^[a-z][a-z0-9+.-]*:/i;
+function absoluteImageUrl(src, options = {}) {
+  const url = options.imageUrl?.(src) || src;
+  if (ABSOLUTE.test(url) || !options.origin) return url;
+  try {
+    return new URL(url, `${options.origin.replace(/\/+$/, "")}/`).href;
+  } catch {
+    return url;
+  }
+}
+function serializeProduct(p, options = {}) {
   return {
     sku: p.sku,
     name: p.name,
@@ -78,7 +126,7 @@ function serializeProduct(p) {
     position: p.position,
     legacy_path: p.legacyPath,
     categories: p.categories.map((c) => ({ id: c.id, slug: c.slug, name: c.name })),
-    images: p.images.map((i) => ({ url: i.url, alt: i.alt, position: i.position })),
+    images: p.images.map((i) => ({ url: absoluteImageUrl(i.url, options), alt: i.alt, position: i.position })),
     inventory: p.inventory ? { available: p.inventory.available, allow_backorder: p.inventory.allowBackorder, updated_at: p.inventory.updatedAt } : null,
     created_at: p.createdAt,
     updated_at: p.updatedAt
@@ -370,6 +418,55 @@ function validateOrderPatch(body) {
   finish(details, "Invalid order patch");
   return out;
 }
+function validateQuotePatch(body) {
+  const details = {};
+  const out = {};
+  if ("external_reference" in body) {
+    const ref = str(details, body, "external_reference", "external_reference", { nullable: true, max: 64 });
+    if (ref !== void 0) out.external_reference = ref;
+  }
+  if (body.status !== void 0) {
+    if (body.status !== "cancelled") details.status = 'can only be set to "cancelled"';
+    else out.status = "cancelled";
+  }
+  if (body.offer !== void 0) {
+    if (!isObject(body.offer)) details.offer = "must be an object";
+    else {
+      const o = body.offer;
+      const lines = [];
+      if (!Array.isArray(o.lines) || o.lines.length === 0) details["offer.lines"] = "must be a non-empty array";
+      else
+        o.lines.forEach((raw, i) => {
+          if (!isObject(raw)) {
+            details[`offer.lines.${i}`] = "must be an object";
+            return;
+          }
+          const sku = str(details, raw, "sku", `offer.lines.${i}.sku`, { required: true, max: 100 });
+          const name = str(details, raw, "name", `offer.lines.${i}.name`, { nullable: true, max: 300 });
+          if (!isInt(raw.quantity) || raw.quantity < 1) details[`offer.lines.${i}.quantity`] = "must be an integer of at least 1";
+          const unit = moneyField(details, raw.unit_amount, `offer.lines.${i}.unit_amount`, { required: true });
+          if (sku && isInt(raw.quantity) && raw.quantity >= 1 && unit) lines.push({ sku: sku.trim(), name: name ?? null, quantity: raw.quantity, unit_amount: unit });
+        });
+      const shipping = moneyField(details, o.shipping, "offer.shipping", { nullable: true });
+      const tax = moneyField(details, o.tax, "offer.tax", { nullable: true });
+      const expiresAt = isoDate(details, o.expires_at, "offer.expires_at");
+      const note = str(details, o, "note", "offer.note", { nullable: true, max: 4e3 });
+      if (o.notify_customer !== void 0 && typeof o.notify_customer !== "boolean") details["offer.notify_customer"] = "must be a boolean";
+      out.offer = {
+        lines,
+        shipping: shipping ?? null,
+        tax: tax ?? null,
+        expires_at: expiresAt ?? null,
+        note: note ?? null,
+        notify_customer: o.notify_customer === void 0 ? true : o.notify_customer
+      };
+    }
+  }
+  if (out.status && out.offer) details.status = "cannot be combined with an offer";
+  if (!("external_reference" in body) && body.status === void 0 && body.offer === void 0) details.body = "must include external_reference, status or offer";
+  finish(details, "Invalid quote patch");
+  return out;
+}
 
 // src/api/index.ts
 var STORE_API_BASES = ["/api/store/v1", "/api/skuio/v1"];
@@ -395,7 +492,8 @@ async function handleStoreApi(request, options) {
     if (scope && caller.kind === "connection" && !caller.connection.scopes.includes(scope)) {
       return error(403, "forbidden", `This connection was not approved for "${scope}"; reconnect and approve it at /admin/connect`);
     }
-    return await route(method, path, url, request, options.store, caller);
+    const images = { imageUrl: options.imageUrl, origin: url.origin };
+    return await route(method, path, url, request, options.store, caller, images);
   } catch (e) {
     if (e instanceof ValidationError) return error(422, "validation_failed", e.message, e.details);
     if (e instanceof StoreError) return error(e.status, e.code, e.message, e.details);
@@ -448,9 +546,10 @@ function scopeFor(path) {
   if (first === "orders") return /^\/orders\/[^/]+\/fulfillments$/.test(path) ? "fulfillments" : "orders";
   if (first === "inventory") return "inventory";
   if (first === "products" || first === "categories") return "catalog";
+  if (first === "quotes") return "quotes";
   return null;
 }
-async function route(method, path, url, request, store, caller) {
+async function route(method, path, url, request, store, caller, images) {
   const segments = path.split("/").filter(Boolean);
   if (path === "/health" && method === "GET") {
     const health = await store.health();
@@ -498,6 +597,27 @@ async function route(method, path, url, request, store, caller) {
       return json({ data: serializeFulfillment(result.fulfillment) }, result.created ? 201 : 200);
     }
   }
+  if (segments[0] === "quotes") {
+    const prefix = store.config.quotes.numberPrefix;
+    if (segments.length === 1 && method === "GET") {
+      const query = validateListQuery(url.searchParams, { defaultLimit: 50, maxLimit: 200, allowUpdatedSince: true });
+      await store.quotes.expireStale();
+      const page = await store.quotes.changedSince(query.updatedSince, query.cursor, query.limit);
+      return json({ data: page.quotes.map((q) => serializeQuote(q, prefix)), next_cursor: page.nextCursor });
+    }
+    const id = segments[1] ? decodeURIComponent(segments[1]) : "";
+    if (segments.length === 2 && id) {
+      if (method === "GET") return json({ data: serializeQuote(await store.quotes.require(id), prefix) });
+      if (method === "PATCH") {
+        const patch = validateQuotePatch(await readJson(request));
+        let quote = await store.quotes.require(id);
+        if (patch.external_reference !== void 0) quote = await store.quotes.setExternalReference(id, patch.external_reference);
+        if (patch.offer) quote = await store.quotes.offer(id, patch.offer);
+        if (patch.status === "cancelled") quote = await store.quotes.cancel(id, "Cancelled by the operations system");
+        return json({ data: serializeQuote(quote, prefix) });
+      }
+    }
+  }
   if (path === "/inventory" && method === "PUT") {
     const items = validateInventory(await readJson(request));
     return json({ data: await store.inventory.set(items) });
@@ -509,11 +629,11 @@ async function route(method, path, url, request, store, caller) {
   if (path === "/products" && method === "GET") {
     const query = validateListQuery(url.searchParams, { defaultLimit: 50, maxLimit: 200, allowUpdatedSince: true, allowActive: true });
     const page = await store.catalog.listProducts(query);
-    return json({ data: page.products.map(serializeProduct), next_cursor: page.nextCursor });
+    return json({ data: page.products.map((p) => serializeProduct(p, images)), next_cursor: page.nextCursor });
   }
   if (segments[0] === "products" && segments.length === 2) {
     const sku = decodeURIComponent(segments[1]);
-    if (method === "GET") return json({ data: serializeProduct(await store.catalog.requireProduct(sku)) });
+    if (method === "GET") return json({ data: serializeProduct(await store.catalog.requireProduct(sku), images) });
     if (method === "DELETE") {
       const done = await store.catalog.deactivateProduct(sku);
       if (!done) return error(404, "not_found", `Product ${sku} not found`);
@@ -535,11 +655,13 @@ export {
   STORE_API_BASE,
   STORE_API_BASES,
   ValidationError,
+  absoluteImageUrl,
   handleStoreApi,
   serializeCategory,
   serializeConnection,
   serializeFulfillment,
   serializeOrder,
-  serializeProduct
+  serializeProduct,
+  serializeQuote
 };
 //# sourceMappingURL=api.js.map