@kotao/storefront 0.2.0

package/dist/client-D9YYA2w6.d.ts

@@ -0,0 +1,159 @@
+interface CacheStrategy {
+    readonly mode: 'none' | 'short' | 'long' | 'custom';
+    /** seconds the value is considered fresh */
+    readonly maxAge: number;
+    /** extra seconds the stale value may be served while revalidating */
+    readonly staleWhileRevalidate: number;
+}
+declare const CacheNone: () => CacheStrategy;
+declare const CacheShort: (o?: Partial<Omit<CacheStrategy, "mode">>) => CacheStrategy;
+declare const CacheLong: (o?: Partial<Omit<CacheStrategy, "mode">>) => CacheStrategy;
+declare const CacheCustom: (s: Omit<CacheStrategy, "mode">) => CacheStrategy;
+/** Hydrogen-parity storefront sub-request default: fresh 1s, serveable up to ~1 day. */
+declare const StorefrontDefaultCache: () => CacheStrategy;
+declare function generateCacheControlHeader(strategy: CacheStrategy): string;
+interface KotaoCache {
+    run<T>(key: string, strategy: CacheStrategy, fn: () => Promise<T>): Promise<T>;
+    readonly raw: Cache;
+}
+/**
+ * Stale-while-revalidate cache over an injected Cache (WFP untrusted mode disables
+ * `caches.default`; each user Worker gets an isolated `caches.open(...)`). `now` is injectable
+ * for deterministic tests and to sidestep workerd's intra-request frozen clock — only
+ * cross-request age is ever compared, which `Date.now()` reports correctly.
+ */
+declare function createCache(opts: {
+    cache: Cache;
+    waitUntil: (p: Promise<unknown>) => void;
+    now?: () => number;
+}): KotaoCache;
+
+interface StorefrontQueryOptions {
+    variables?: Record<string, unknown>;
+    cache?: CacheStrategy;
+    storefrontApiVersion?: string;
+}
+interface StorefrontLooseConnection<T = any> {
+    readonly nodes: T[];
+    readonly pageInfo: any;
+}
+interface StorefrontLooseProductCollection {
+    readonly description: string;
+    readonly handle: string;
+    readonly id: string;
+    readonly products: StorefrontLooseConnection & {
+        readonly filters: readonly {
+            readonly values: readonly {
+                readonly id: string;
+                readonly input?: string | null;
+                readonly label: string;
+            }[];
+        }[];
+    };
+    readonly title: string;
+}
+interface StorefrontDefaultQueryData {
+    [key: string]: any;
+    additional: StorefrontLooseConnection;
+    articles: StorefrontLooseConnection;
+    blog: {
+        readonly articles: StorefrontLooseConnection;
+        readonly seo?: any;
+        readonly title: string;
+    };
+    blogs: StorefrontLooseConnection;
+    collection: StorefrontLooseProductCollection;
+    collections: StorefrontLooseConnection<{
+        handle: string;
+        title: string;
+    }>;
+    page: any;
+    policies: any[];
+    product: any;
+    products: StorefrontLooseConnection;
+    recommended: any[];
+    search: StorefrontLooseConnection;
+    shop: any;
+}
+interface StorefrontQueryPromise<T> extends Promise<T> {
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<T | TResult>;
+}
+interface StorefrontClient {
+    query<T = StorefrontDefaultQueryData>(query: string, options?: StorefrontQueryOptions): StorefrontQueryPromise<T>;
+    mutate<T = any>(mutation: string, options?: {
+        variables?: Record<string, unknown>;
+    }): Promise<T>;
+    CacheNone: typeof CacheNone;
+    CacheShort: typeof CacheShort;
+    CacheLong: typeof CacheLong;
+    CacheCustom: typeof CacheCustom;
+    readonly cache: Cache;
+    readonly i18n: StorefrontI18n;
+}
+type Storefront<I18n = unknown> = StorefrontClient & {
+    readonly i18n: I18n;
+};
+type StorefrontClientResult<I18n = StorefrontI18n> = Storefront<I18n> & {
+    readonly storefront: Storefront<I18n>;
+};
+interface StorefrontI18n {
+    readonly language: string;
+    readonly country: string;
+    readonly currency: string;
+    readonly pathPrefix: string;
+}
+type StorefrontAuthHeader = 'x-kotao-storefront-token' | 'x-api-key' | 'x-shopify-storefront-access-token';
+interface StorefrontClientOptions {
+    endpoint: string;
+    token: string;
+    tokenHeader?: StorefrontAuthHeader;
+    siteId?: string;
+    cache: KotaoCache;
+    fetch?: typeof fetch | undefined;
+    defaultStrategy?: CacheStrategy | undefined;
+    /**
+     * Pre-signed `x-kotao-shop` / `x-kotao-shop-signature` header pair, merged into every request.
+     * In production the Gateway signs the shop-context; in local dev (no Gateway) the theme dev
+     * server signs it (see createKotaoContext). Absent in production.
+     */
+    signedShopContextHeaders?: Readonly<Record<string, string>> | undefined;
+    /**
+     * Additional server request headers to forward to direct Storefront API calls. Used by
+     * Hydrogen-compatible server adapters for `storefrontHeaders`.
+     */
+    extraHeaders?: HeadersInit | undefined;
+    /**
+     * BCP 47 locale tag derived from the localization cookie (e.g. `'nl'`, `'es'`, `'de-de'`).
+     * When set, `x-kotao-locale` is added to every request so storefront-api can overlay
+     * translations. Also folds into the SWR cache key so locales never share a cached response.
+     */
+    locale?: string | undefined;
+    /**
+     * ISO 3166-1 alpha-2 country selected by the localization cookie. When valid, sent as
+     * `x-kotao-country` and folded into the SWR key so country-specific prices never share cache.
+     */
+    country?: string | undefined;
+    i18n?: Partial<StorefrontI18n> | undefined;
+}
+interface HydrogenStorefrontClientOptions<I18n extends object = StorefrontI18n> {
+    cache: Cache;
+    waitUntil: (promise: Promise<unknown>) => void;
+    i18n?: I18n | undefined;
+    publicStorefrontToken: string;
+    privateStorefrontToken?: string | undefined;
+    storeDomain: string;
+    storefrontId?: string | undefined;
+    storefrontHeaders?: HeadersInit | undefined;
+    storefrontApiVersion?: string | undefined;
+    fetch?: typeof fetch | undefined;
+    defaultStrategy?: CacheStrategy | undefined;
+}
+/**
+ * Typed GraphQL client mirroring Hydrogen's `createStorefrontClient`. Queries are SWR-cached
+ * (default {@link StorefrontDefaultCache}); mutations are never cached. Talks to the same-origin
+ * `/api/storefront` proxy (#85) so tokens stay server-side and themes need no CORS.
+ */
+declare function createStorefrontClient(opts: StorefrontClientOptions): StorefrontClientResult;
+declare function createStorefrontClient<I18n extends object = StorefrontI18n>(opts: HydrogenStorefrontClientOptions<I18n>): StorefrontClientResult<StorefrontI18n & I18n>;
+
+export { type CacheStrategy as C, type HydrogenStorefrontClientOptions as H, type KotaoCache as K, type StorefrontClient as S, CacheCustom as a, CacheLong as b, CacheNone as c, CacheShort as d, type Storefront as e, type StorefrontAuthHeader as f, type StorefrontClientOptions as g, type StorefrontClientResult as h, StorefrontDefaultCache as i, type StorefrontQueryOptions as j, createCache as k, createStorefrontClient as l, generateCacheControlHeader as m };

package/dist/customer-account-api-types.d.ts

@@ -0,0 +1,144 @@
+type Maybe<T> = T | null;
+type InputMaybe<T> = Maybe<T>;
+type Exact<T extends Record<string, unknown>> = {
+    [K in keyof T]: T[K];
+};
+interface Scalars {
+    readonly ID: {
+        readonly input: string;
+        readonly output: string;
+    };
+    readonly String: {
+        readonly input: string;
+        readonly output: string;
+    };
+    readonly Boolean: {
+        readonly input: boolean;
+        readonly output: boolean;
+    };
+    readonly Int: {
+        readonly input: number;
+        readonly output: number;
+    };
+    readonly Float: {
+        readonly input: number;
+        readonly output: number;
+    };
+    readonly DateTime: {
+        readonly input: string;
+        readonly output: string;
+    };
+    readonly [key: string]: {
+        readonly input: any;
+        readonly output: any;
+    };
+}
+interface LooseObject {
+    [key: string]: any;
+}
+type FulfillmentStatus = string;
+interface MoneyV2 extends LooseObject {
+    readonly amount: string;
+    readonly currencyCode: string;
+}
+interface Image extends LooseObject {
+    readonly altText?: string | null;
+    readonly height?: number | null;
+    readonly url: string;
+    readonly width?: number | null;
+}
+interface CustomerPhoneNumber extends LooseObject {
+    readonly phoneNumber: string;
+}
+interface CustomerEmailAddress extends LooseObject {
+    readonly emailAddress: string;
+}
+interface CustomerAddressInput {
+    address1?: string | null;
+    address2?: string | null;
+    city?: string | null;
+    company?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    phoneNumber?: string | null;
+    territoryCode?: string | null;
+    zip?: string | null;
+    zoneCode?: string | null;
+}
+interface CustomerAddress extends CustomerAddressInput {
+    readonly formatted?: readonly string[];
+    readonly formattedArea?: string | null;
+    readonly id: string;
+    readonly name?: string | null;
+}
+interface CustomerUpdateInput {
+    firstName?: string | null;
+    lastName?: string | null;
+    phoneNumber?: string | null;
+}
+interface Customer extends LooseObject {
+    readonly addresses?: {
+        readonly edges?: readonly {
+            readonly node: CustomerAddress;
+        }[];
+    };
+    readonly defaultAddress?: CustomerAddress | null;
+    readonly emailAddress?: CustomerEmailAddress | null;
+    readonly firstName?: string | null;
+    readonly id?: string;
+    readonly lastName?: string | null;
+    readonly phoneNumber?: CustomerPhoneNumber | null;
+}
+interface UserErrorsCustomerAddressUserErrors extends LooseObject {
+    readonly code?: string | null;
+    readonly field?: readonly string[] | null;
+    readonly message: string;
+}
+interface UserErrorsCustomerUserErrors extends LooseObject {
+    readonly code?: string | null;
+    readonly field?: readonly string[] | null;
+    readonly message: string;
+}
+interface CustomerAddressDeletePayload extends LooseObject {
+    readonly deletedAddressId?: string | null;
+    readonly userErrors?: readonly UserErrorsCustomerAddressUserErrors[];
+}
+interface Fulfillment extends LooseObject {
+    readonly status: FulfillmentStatus;
+}
+interface LineItem extends LooseObject {
+    readonly id?: string;
+    readonly image?: Image | null;
+    readonly quantity?: number;
+    readonly title: string;
+    readonly variantTitle?: string | null;
+}
+interface PricingPercentageValue extends LooseObject {
+    readonly percentage: number;
+}
+interface Order extends LooseObject {
+    readonly discountApplications?: {
+        readonly nodes?: readonly LooseObject[];
+    };
+    readonly financialStatus?: string | null;
+    readonly fulfillments?: {
+        readonly nodes?: readonly Fulfillment[];
+    };
+    readonly id: string;
+    readonly lineItems?: {
+        readonly edges?: readonly {
+            readonly node: LineItem;
+        }[];
+        readonly nodes?: readonly LineItem[];
+    };
+    readonly name?: string;
+    readonly number?: string | number;
+    readonly processedAt: string;
+    readonly shippingAddress?: CustomerAddress | null;
+    readonly statusPageUrl?: string;
+    readonly subtotal?: MoneyV2 | null;
+    readonly totalTax?: MoneyV2 | null;
+    readonly totalPrice?: MoneyV2;
+}
+
+export type { Customer, CustomerAddress, CustomerAddressDeletePayload, CustomerAddressInput, CustomerEmailAddress, CustomerPhoneNumber, CustomerUpdateInput, Exact, Fulfillment, FulfillmentStatus, Image, InputMaybe, LineItem, Maybe, MoneyV2, Order, PricingPercentageValue, Scalars, UserErrorsCustomerAddressUserErrors, UserErrorsCustomerUserErrors };

package/dist/customer-account-api-types.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=customer-account-api-types.js.map
+//# sourceMappingURL=customer-account-api-types.js.map

package/dist/customer-account-api-types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"customer-account-api-types.js"}

package/dist/editor.d.ts

@@ -0,0 +1,112 @@
+import { c as ThemeSettingsStore, b as ResolvedSettings, a as ResolvedSection, R as ResolvedBlock } from './store-DQK1nhob.js';
+
+interface StorefrontEditorMessageTarget {
+    postMessage(message: unknown, targetOrigin: string): void;
+}
+interface StorefrontEditorMessageEvent {
+    readonly origin: string;
+    readonly data: unknown;
+    readonly source?: StorefrontEditorMessageTarget | null;
+}
+interface StorefrontEditorMessageSource {
+    addEventListener(type: 'message', listener: (event: StorefrontEditorMessageEvent) => void): void;
+    removeEventListener(type: 'message', listener: (event: StorefrontEditorMessageEvent) => void): void;
+}
+interface StorefrontEditorBridge {
+    ready(): void;
+    selectSection(sectionId: string): void;
+    dispose(): void;
+}
+interface StorefrontEditorSettingOption {
+    readonly value: string;
+    readonly label: string;
+}
+interface StorefrontEditorSettingInput {
+    readonly type: string;
+    readonly name: string;
+    readonly label: string;
+    readonly defaultValue?: unknown;
+    readonly placeholder?: string;
+    readonly helpText?: string;
+    readonly options?: readonly StorefrontEditorSettingOption[];
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+    readonly unit?: string;
+}
+interface StorefrontEditorBlockSchema {
+    readonly type: string;
+    readonly label: string;
+    readonly settings: readonly StorefrontEditorSettingInput[];
+}
+interface StorefrontEditorSectionPresetBlock {
+    readonly type: string;
+    readonly settings?: ResolvedSettings;
+}
+interface StorefrontEditorSectionPreset {
+    readonly name: string;
+    readonly settings?: ResolvedSettings;
+    readonly blocks?: readonly StorefrontEditorSectionPresetBlock[];
+}
+interface StorefrontEditorSectionSchema {
+    readonly type: string;
+    readonly label: string;
+    readonly settings: readonly StorefrontEditorSettingInput[];
+    readonly blocks?: readonly StorefrontEditorBlockSchema[];
+    readonly presets?: readonly StorefrontEditorSectionPreset[];
+}
+interface StorefrontEditorSelection {
+    readonly sectionId: string;
+    readonly section?: ResolvedSection;
+    readonly sections?: readonly ResolvedSection[];
+    readonly schema?: StorefrontEditorSectionSchema;
+    readonly schemas?: Readonly<Record<string, StorefrontEditorSectionSchema>>;
+}
+interface StorefrontEditorValuesDocument {
+    readonly shopId: string;
+    readonly sections: readonly ResolvedSection[];
+}
+interface StorefrontEditorReady {
+    readonly sections: readonly ResolvedSection[];
+    readonly schemas?: Readonly<Record<string, StorefrontEditorSectionSchema>>;
+    readonly globalInputs?: readonly StorefrontEditorSettingInput[];
+    readonly templates?: Readonly<Record<string, StorefrontEditorValuesDocument>>;
+    readonly sectionGroups?: Readonly<Record<string, StorefrontEditorValuesDocument>>;
+}
+interface StorefrontEditorHostBridge {
+    patchSection(sectionId: string, settings: ResolvedSettings): void;
+    patchGlobal(settings: ResolvedSettings): void;
+    insertSection(section: ResolvedSection, index?: number): void;
+    removeSection(sectionId: string): void;
+    reorderSection(sectionId: string, index: number): void;
+    patchBlock(sectionId: string, blockId: string, settings: ResolvedSettings): void;
+    insertBlock(sectionId: string, block: ResolvedBlock, index?: number): void;
+    removeBlock(sectionId: string, blockId: string): void;
+    reorderBlock(sectionId: string, blockId: string, index: number): void;
+    replaceTemplate(handle: string, document: StorefrontEditorValuesDocument): void;
+    replaceSectionGroup(handle: string, document: StorefrontEditorValuesDocument): void;
+    dispose(): void;
+}
+interface CreateStorefrontEditorBridgeArgs {
+    readonly adminOrigin: string;
+    readonly shopId: string;
+    readonly store: ThemeSettingsStore;
+    readonly schemas?: Readonly<Record<string, StorefrontEditorSectionSchema>>;
+    readonly globalInputs?: readonly StorefrontEditorSettingInput[];
+    readonly templates?: Readonly<Record<string, StorefrontEditorValuesDocument>>;
+    readonly sectionGroups?: Readonly<Record<string, StorefrontEditorValuesDocument>>;
+    readonly transport: StorefrontEditorMessageSource;
+    readonly target: StorefrontEditorMessageTarget;
+}
+interface CreateStorefrontEditorHostBridgeArgs {
+    readonly onSelectSection: (selection: StorefrontEditorSelection) => void;
+    readonly onReady?: (ready: StorefrontEditorReady) => void;
+    readonly previewOrigin: string;
+    readonly shopId: string;
+    readonly transport: StorefrontEditorMessageSource;
+    readonly target: StorefrontEditorMessageTarget;
+}
+declare function createStorefrontEditorBridge({ adminOrigin, globalInputs, schemas, sectionGroups, shopId, store, target, templates, transport, }: CreateStorefrontEditorBridgeArgs): StorefrontEditorBridge;
+declare function createStorefrontEditorHostBridge({ onReady, onSelectSection, previewOrigin, shopId, target, transport, }: CreateStorefrontEditorHostBridgeArgs): StorefrontEditorHostBridge;
+
+export { type CreateStorefrontEditorBridgeArgs, type CreateStorefrontEditorHostBridgeArgs, type StorefrontEditorBlockSchema, type StorefrontEditorBridge, type StorefrontEditorHostBridge, type StorefrontEditorMessageEvent, type StorefrontEditorMessageSource, type StorefrontEditorMessageTarget, type StorefrontEditorReady, type StorefrontEditorSectionPreset, type StorefrontEditorSectionPresetBlock, type StorefrontEditorSectionSchema, type StorefrontEditorSelection, type StorefrontEditorSettingInput, type StorefrontEditorSettingOption, type StorefrontEditorValuesDocument, createStorefrontEditorBridge, createStorefrontEditorHostBridge };

package/dist/editor.js

@@ -0,0 +1,3 @@
+export { createStorefrontEditorBridge, createStorefrontEditorHostBridge } from './chunk-PXZ737N3.js';
+//# sourceMappingURL=editor.js.map
+//# sourceMappingURL=editor.js.map

package/dist/editor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"editor.js"}

package/dist/image.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Framework-agnostic image-URL builders for the storefront SDK (ADR-0003 §SDK image-URL contract).
+ * They build Cloudflare `/cdn-cgi/image/<opts>/<path>` path-form transform URLs for `https://cdn.kotao.*`
+ * bases, allowing the CDN to serve optimized renderings. Non-CDN URLs (external, data:, theme `/assets/...`)
+ * pass through unchanged. Wire-native params — `width`/`height`/`fit`/`format`/`quality` — matching
+ * Cloudflare's native image resizing; a Hydrogen-shaped React `<Image>` (with `crop`, `srcSet`/`sizes`
+ * props) layers on top in the framework presets (#92). Pure string building, no framework imports, so it
+ * stays in the SDK core.
+ */
+/** Cloudflare-native resize mode (the Gateway's `fit` param). */
+type ImageFit = 'scale-down' | 'contain' | 'pad' | 'squeeze' | 'cover' | 'crop';
+/** Output format query value (the Gateway maps it to a content-type). */
+type ImageFormat = 'webp' | 'avif' | 'jpeg' | 'png';
+interface ImageUrlOptions {
+    width?: number;
+    height?: number;
+    fit?: ImageFit;
+    format?: ImageFormat;
+    /** 1–100. */
+    quality?: number;
+}
+/**
+ * Build a Cloudflare `/cdn-cgi/image/` path-form transform URL for a CDN image. For transformable
+ * URLs (absolute `https://cdn.kotao.*`), emits `/cdn-cgi/image/{opts}/{path}` where `{opts}` is
+ * the comma-joined key=value list (in stable order: width,height,fit,format,quality) and `{path}`
+ * is the original pathname. Chaining replaces any existing `/cdn-cgi/image/` segment.
+ * Non-CDN URLs pass through unchanged.
+ */
+declare function imageUrl(url: string, options?: ImageUrlOptions): string;
+interface ImageSrcSetOptions extends Omit<ImageUrlOptions, 'width'> {
+    /** Candidate widths (px) for the `srcset` descriptors. */
+    widths: number[];
+}
+/**
+ * Build a `srcset` string — one `url width` candidate per width — for responsive `<img srcset>` /
+ * `<source srcset>`. Pair with a `sizes` attribute the theme controls.
+ */
+declare function imageSrcSet(url: string, options: ImageSrcSetOptions): string;
+
+/**
+ * Framework-agnostic `<img>` attribute builder (ADR-0003 §SDK image-URL contract). Turns the
+ * Hydrogen-shaped `<Image>` surface (data/aspectRatio/crop/sizes/width/height) into concrete img
+ * attributes (src, srcSet, sizes, width, height, style) over the `cdn.kotao.*` R2-native transform
+ * contract, via the pure `imageUrl`/`imageSrcSet` builders. The React `<Image>` is a thin wrapper
+ * that spreads these — so all logic lives here, in the core, unit-tested without a DOM.
+ */
+
+interface ImageData {
+    url: string;
+    altText?: string | null;
+    width?: number | null;
+    height?: number | null;
+}
+/** Hydrogen crop region. v1 maps any crop to a fill+crop (Cloudflare `fit=cover`); positional gravity
+ * (top/bottom/left/right) is not on the wire yet, so all values currently centre-crop. */
+type ImageCrop = 'center' | 'top' | 'bottom' | 'left' | 'right';
+interface ImageAttrsOptions {
+    data: ImageData;
+    /** Override `data.url`. */
+    src?: string | undefined;
+    /** "width/height" (e.g. "4/5") — sets the intrinsic box for CLS-free layout. */
+    aspectRatio?: string | undefined;
+    crop?: ImageCrop | undefined;
+    /** The responsive `sizes` attribute; the theme owns it. */
+    sizes?: string | undefined;
+    /** Fixed render width (px). With it, the srcSet becomes 1x/2x/3x instead of the responsive set. */
+    width?: number | undefined;
+    height?: number | undefined;
+    loading?: ('eager' | 'lazy') | undefined;
+    /** srcSet candidate widths; defaults to a responsive set (or 1x/2x/3x when `width` is fixed). */
+    srcSetWidths?: number[] | undefined;
+    format?: ImageFormat | undefined;
+    quality?: number | undefined;
+}
+interface ImageAttrs {
+    src: string;
+    srcSet: string;
+    sizes?: string;
+    width?: number;
+    height?: number;
+    alt: string;
+    loading: 'eager' | 'lazy';
+    style?: {
+        aspectRatio: string;
+    };
+}
+declare function buildImageAttrs(options: ImageAttrsOptions): ImageAttrs;
+
+export { type ImageAttrs, type ImageAttrsOptions, type ImageCrop, type ImageData, type ImageFit, type ImageFormat, type ImageSrcSetOptions, type ImageUrlOptions, buildImageAttrs, imageSrcSet, imageUrl };

package/dist/image.js

@@ -0,0 +1,3 @@
+export { buildImageAttrs, imageSrcSet, imageUrl } from './chunk-3YQXJNR7.js';
+//# sourceMappingURL=image.js.map
+//# sourceMappingURL=image.js.map

package/dist/image.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"image.js"}