@ekomerc/storefront 0.1.0 → 0.1.3

package/dist/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ekomerc/storefront",
+  "version": "0.1.3",
+  "description": "TypeScript SDK for ekomerc storefronts",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./index.cjs"
+      }
+    },
+    "./types": {
+      "import": {
+        "types": "./types.d.ts",
+        "default": "./types.js"
+      },
+      "require": {
+        "types": "./types.d.cts",
+        "default": "./types.cjs"
+      }
+    },
+    "./errors": {
+      "import": {
+        "types": "./errors.d.ts",
+        "default": "./errors.js"
+      },
+      "require": {
+        "types": "./errors.d.cts",
+        "default": "./errors.cjs"
+      }
+    }
+  },
+  "dependencies": {
+    "neverthrow": "8.2.0"
+  }
+}

package/dist/types.d.cts

@@ -0,0 +1,656 @@
+import { Result } from 'neverthrow';
+
+/**
+ * Base class for all Storefront SDK errors
+ */
+declare class StorefrontError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string, options?: {
+        cause?: Error;
+    });
+}
+
+declare const TRACKING_POLICY_EVENT_TYPES: readonly ["analytics.page_view", "analytics.product_view", "analytics.collection_view", "analytics.search_performed", "analytics.add_to_cart", "analytics.remove_from_cart", "analytics.checkout_started", "analytics.checkout_step_completed", "analytics.checkout_completed", "analytics.custom"];
+type TrackingPolicyEventType = (typeof TRACKING_POLICY_EVENT_TYPES)[number];
+declare const TRACKING_PROVIDERS: readonly ["gtm", "meta", "tiktok"];
+type TrackingProvider = (typeof TRACKING_PROVIDERS)[number];
+
+/**
+ * Consent states emitted with browser-side analytics events.
+ */
+type AnalyticsConsentState = "granted" | "denied" | "unknown";
+/**
+ * Runtime policies controlling how consent gates browser event dispatch.
+ */
+type AnalyticsDispatchOnUnknownConsent = boolean;
+/**
+ * UTM parameters captured for a visitor session.
+ */
+interface AnalyticsUtm {
+    schemaVersion: 1;
+    source: string | null;
+    medium: string | null;
+    campaign: string | null;
+    term: string | null;
+    content: string | null;
+}
+/**
+ * Click identifiers captured from ad platforms and passed through analytics events.
+ */
+interface AnalyticsClickIds {
+    schemaVersion: 1;
+    capturedAt: string | null;
+    gclid: string | null;
+    gbraid: string | null;
+    wbraid: string | null;
+    ttclid: string | null;
+    fbclid: string | null;
+}
+/**
+ * Request context attached to each browser analytics event.
+ */
+interface AnalyticsEventContextPayload {
+    schemaVersion: 1;
+    path: string;
+}
+/**
+ * Primitive JSON values supported inside analytics properties.
+ */
+type AnalyticsJsonPrimitive = string | number | boolean | null;
+/**
+ * Recursive JSON value shape supported by analytics event properties.
+ */
+type AnalyticsJsonValue = AnalyticsJsonPrimitive | AnalyticsJsonValue[] | {
+    [key: string]: AnalyticsJsonValue;
+};
+/**
+ * Arbitrary analytics event properties sent to ingest and browser adapters.
+ */
+interface AnalyticsProperties {
+    [key: string]: AnalyticsJsonValue;
+}
+/**
+ * Best-effort browser device fingerprint attached to an analytics event.
+ */
+interface AnalyticsBrowserEventDevice {
+    deviceType: string;
+    deviceOs: string | null;
+    deviceBrowser: string | null;
+}
+/**
+ * Canonical browser analytics event shape used by the storefront SDK.
+ */
+interface AnalyticsBrowserEvent {
+    schemaVersion: 1;
+    eventId: string;
+    eventType: TrackingPolicyEventType;
+    occurredAt: string;
+    sessionId: string;
+    visitorId: string;
+    customerId: string | null;
+    consentState: AnalyticsConsentState;
+    context: AnalyticsEventContextPayload;
+    referrer: string | null;
+    utm: AnalyticsUtm;
+    clickIds: AnalyticsClickIds;
+    device: AnalyticsBrowserEventDevice;
+    properties: AnalyticsProperties;
+}
+/**
+ * Consent state payload passed to browser adapters and diagnostics.
+ */
+interface AnalyticsConsentUpdate {
+    consentState: AnalyticsConsentState;
+    dispatchOnUnknownConsent: AnalyticsDispatchOnUnknownConsent;
+}
+/**
+ * Input provided to a browser adapter when dispatching an analytics event.
+ */
+interface AnalyticsAdapterDispatchInput {
+    event: AnalyticsBrowserEvent;
+    consent: AnalyticsConsentUpdate;
+}
+/**
+ * Reasons a browser adapter may skip dispatch instead of throwing.
+ */
+type AnalyticsAdapterSkipReason = "unsupported_event" | "consent_blocked" | "runtime_unavailable";
+/**
+ * Structured result returned when a browser adapter intentionally skips dispatch.
+ */
+interface AnalyticsAdapterOperationSkippedResult {
+    status: "skipped";
+    reason: "runtime_unavailable";
+}
+/**
+ * Result returned by browser adapter dispatch and consent-update hooks.
+ */
+type AnalyticsAdapterOperationResult = void | {
+    status: "success";
+} | AnalyticsAdapterOperationSkippedResult;
+/**
+ * Browser-side analytics adapter contract for GTM, Meta, TikTok, or custom integrations.
+ */
+interface AnalyticsBrowserAdapter {
+    provider: TrackingProvider;
+    dispatch(input: AnalyticsAdapterDispatchInput): AnalyticsAdapterOperationResult | Promise<AnalyticsAdapterOperationResult>;
+    updateConsent?(input: AnalyticsConsentUpdate): AnalyticsAdapterOperationResult | Promise<AnalyticsAdapterOperationResult>;
+}
+/**
+ * Diagnostic events emitted by the analytics runtime for ingest and adapter activity.
+ */
+type AnalyticsDiagnostic = {
+    target: "ingest";
+    status: "success";
+    event: AnalyticsBrowserEvent;
+    response: {
+        acceptedCount: number;
+        duplicateCount: number;
+        rejectedCount: number;
+    };
+} | {
+    target: "ingest";
+    status: "error";
+    event: AnalyticsBrowserEvent;
+    error: Error;
+} | {
+    target: "ingest";
+    status: "accepted_unknown";
+    event: AnalyticsBrowserEvent;
+} | {
+    target: "queue";
+    status: "enqueued";
+    event: AnalyticsBrowserEvent;
+} | {
+    target: "queue";
+    status: "flushed";
+    count: number;
+} | {
+    target: "queue";
+    status: "evicted_full";
+    event: AnalyticsBrowserEvent;
+} | {
+    target: "queue";
+    status: "evicted_expired";
+    eventId: string;
+} | {
+    target: "adapter";
+    status: "success";
+    provider: TrackingProvider;
+    event: AnalyticsBrowserEvent;
+} | {
+    target: "adapter";
+    status: "skipped";
+    provider: TrackingProvider;
+    event: AnalyticsBrowserEvent;
+    reason: AnalyticsAdapterSkipReason;
+} | {
+    target: "adapter";
+    status: "error";
+    provider: TrackingProvider;
+    event: AnalyticsBrowserEvent;
+    error: Error;
+} | {
+    target: "consent_bridge";
+    status: "success";
+    provider: TrackingProvider;
+    consent: AnalyticsConsentUpdate;
+} | {
+    target: "consent_bridge";
+    status: "skipped";
+    provider: TrackingProvider;
+    consent: AnalyticsConsentUpdate;
+    reason: "runtime_unavailable";
+} | {
+    target: "consent_bridge";
+    status: "error";
+    provider: TrackingProvider;
+    consent: AnalyticsConsentUpdate;
+    error: Error;
+} | {
+    target: "consent";
+    status: "error";
+    error: Error;
+};
+/**
+ * Optional browser analytics runtime hooks passed to `createStorefrontClient()`.
+ */
+interface StorefrontTrackingRuntimeConfig {
+    dispatchOnUnknownConsent?: AnalyticsDispatchOnUnknownConsent;
+    resolveConsentState?: () => AnalyticsConsentState | Promise<AnalyticsConsentState>;
+    adapters?: AnalyticsBrowserAdapter[];
+    onDiagnostic?: (diagnostic: AnalyticsDiagnostic) => void;
+}
+
+/**
+ * Re-export generated GraphQL types once codegen runs
+ * For now, define placeholder types that will be replaced
+ */
+interface StorageAdapter {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+interface StorefrontClientConfig {
+    endpoint: string;
+    apiKey: string;
+    storage?: StorageAdapter;
+    cacheTTL?: number;
+    /**
+     * How long stored landing attribution remains valid, in milliseconds.
+     * Defaults to 30 days.
+     */
+    trackingAttributionTTL?: number;
+    /**
+     * Deprecated. Pass runtime analytics hooks to `client.init({ analytics: ... })`.
+     */
+    tracking?: StorefrontTrackingRuntimeConfig;
+}
+interface StorefrontAnalyticsInitConfig extends StorefrontTrackingRuntimeConfig {
+    stripUrl?: boolean;
+}
+interface StorefrontInitOptions {
+    analytics?: StorefrontAnalyticsInitConfig;
+}
+interface ResolvedStorefrontAnalyticsConfig {
+    enabled: boolean;
+    dispatchOnUnknownConsent: boolean;
+    gtm: {
+        enabled: boolean;
+        containerId: string | null;
+    };
+}
+interface ResolvedStorefrontInitConfig {
+    analytics: ResolvedStorefrontAnalyticsConfig;
+}
+interface PageInfo {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    startCursor: string | null;
+    endCursor: string | null;
+}
+interface PaginatedResult<T> {
+    items: T[];
+    pageInfo: PageInfo;
+}
+type StorefrontResult<T> = Result<T, StorefrontError>;
+type WeightUnit = "g" | "kg" | "lb" | "oz";
+interface ProductOptionValue {
+    id: string;
+    value: string;
+    position: number;
+}
+interface ProductOption {
+    id: string;
+    name: string;
+    position: number;
+    values: ProductOptionValue[];
+}
+interface ProductImage {
+    id: string;
+    url: string;
+    altText: string | null;
+    position: number;
+}
+interface QuantityPricingTier {
+    minQuantity: number;
+    price: number;
+}
+interface ProductVariant {
+    id: string;
+    title: string;
+    sku: string | null;
+    price: number;
+    compareAtPrice: number | null;
+    weight: number | null;
+    weightUnit: WeightUnit;
+    requiresShipping: boolean;
+    availableForSale: boolean;
+    quantity: number;
+    selectedOptions: ProductOptionValue[];
+    image: ProductImage | null;
+    isOnSale: boolean;
+    quantityPricing: QuantityPricingTier[];
+}
+interface Category {
+    id: string;
+    name: string;
+    handle: string;
+    description: string | null;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    imageAsset: {
+        url: string;
+        altText: string | null;
+        width: number | null;
+        height: number | null;
+    } | null;
+    parent: Category | null;
+    children: Category[];
+    ancestors: Category[];
+    productCount: number;
+}
+interface FlatCategory {
+    id: string;
+    name: string;
+    handle: string;
+    description: string | null;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    imageUrl: string | null;
+    parentId: string | null;
+    depth: number;
+    hasChildren: boolean;
+    productCount: number;
+}
+interface Tag {
+    id: string;
+    name: string;
+}
+type SectionType = "RICH_TEXT" | "BULLET_LIST" | "TABLE";
+type DisplayIntent = "ACCORDION" | "SPECIFICATIONS" | "BOTH";
+interface DetailSectionBase {
+    id: string;
+    title: string;
+    displayIntent: DisplayIntent;
+    position: number;
+}
+interface RichTextDetailSection extends DetailSectionBase {
+    sectionType: "RICH_TEXT";
+    content: {
+        html: string;
+    };
+}
+interface BulletListDetailSection extends DetailSectionBase {
+    sectionType: "BULLET_LIST";
+    content: {
+        items: string[];
+    };
+}
+interface TableDetailSection extends DetailSectionBase {
+    sectionType: "TABLE";
+    content: {
+        rows: [string, string][];
+    };
+}
+type DetailSection = RichTextDetailSection | BulletListDetailSection | TableDetailSection;
+interface Product {
+    id: string;
+    handle: string;
+    title: string;
+    description: string | null;
+    vendor: string | null;
+    productType: string | null;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    publishedAt: string | null;
+    createdAt: string;
+    availableForSale: boolean;
+    media: ProductImage[];
+    options: ProductOption[];
+    variants: ProductVariant[];
+    categories: Category[];
+    primaryCategory: Category | null;
+    tags: Tag[];
+    detailSections: DetailSection[];
+}
+type ProductSortKey = "CREATED_AT" | "TITLE" | "PRICE_ASC" | "PRICE_DESC" | "BEST_SELLING";
+interface ProductFilter {
+    search?: string | null;
+    categoryHandle?: string | null;
+    categoryId?: string | null;
+    includeDescendants?: boolean | null;
+    collectionHandle?: string | null;
+    collectionId?: string | null;
+    tags?: string[] | null;
+    vendor?: string | null;
+    productType?: string | null;
+    minPrice?: number | null;
+    maxPrice?: number | null;
+    availableForSale?: boolean | null;
+}
+type CollectionType = "manual" | "intelligent";
+type CollectionSortOrder = "manual" | "best_selling" | "newest" | "price_asc" | "price_desc";
+interface Collection {
+    id: string;
+    handle: string;
+    title: string;
+    description: string | null;
+    type: CollectionType;
+    sortOrder: CollectionSortOrder;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    productCount: number;
+    imageAsset: {
+        url: string;
+        altText: string | null;
+        width: number | null;
+        height: number | null;
+    } | null;
+}
+interface CartItem {
+    id: string;
+    variantId: string;
+    quantity: number;
+    priceAtAdd: number;
+    effectiveUnitPrice: number;
+    lineTotal: number;
+    taxAmount: number;
+    variant: ProductVariant | null;
+}
+type CartStatus = "active" | "checkout" | "converted" | "expired";
+interface AppliedPromoCode {
+    code: string;
+    discountType: string;
+    discountAmount: number;
+    description: string;
+}
+interface AppliedDiscount {
+    promotionId: string;
+    discountClass: string;
+    discountType: string;
+    discountAmount: number;
+    description: string;
+    isAutomatic: boolean;
+}
+interface Cart {
+    id: string;
+    token: string;
+    status: CartStatus;
+    items: CartItem[];
+    totalItems: number;
+    totalPrice: number;
+    taxTotal: number;
+    shippingTotal: number;
+    total: number;
+    discountTotal: number;
+    appliedPromoCode: AppliedPromoCode | null;
+    appliedDiscounts: AppliedDiscount[];
+    customerEmail: string | null;
+    customerPhone: string | null;
+    shippingAddress: Address | null;
+    billingAddress: Address | null;
+    notes: string | null;
+    paymentMethod: string | null;
+    shippingRateId: string | null;
+    checkoutStartedAt?: string | null;
+    checkoutExpiresAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Address {
+    firstName: string | null;
+    lastName: string | null;
+    company: string | null;
+    addressLine1: string;
+    addressLine2: string | null;
+    city: string;
+    province: string | null;
+    provinceCode: string | null;
+    country: string;
+    countryCode: string;
+    zip: string;
+    phone: string | null;
+}
+interface CheckoutData {
+    email?: string;
+    phone?: string;
+    shippingAddress?: Address;
+    billingAddress?: Address;
+    notes?: string;
+    emailMarketingConsent?: boolean | null;
+    paymentMethod?: string;
+    shippingRateId?: string;
+}
+interface ShippingRate {
+    id: string;
+    name: string;
+    price: number;
+    minOrderAmount: number | null;
+    estimatedDaysMin: number | null;
+    estimatedDaysMax: number | null;
+    isFree: boolean;
+}
+interface AvailablePaymentMethod {
+    method: string;
+    displayName: string;
+    additionalFee: number;
+}
+interface SocialLinks {
+    instagram?: string;
+    facebook?: string;
+    tiktok?: string;
+    twitter?: string;
+}
+/**
+ * Public GTM settings returned by the storefront `store` query.
+ */
+interface GtmBrowserTrackingConfig {
+    enabled: boolean;
+    containerId: string | null;
+}
+/**
+ * Browser-side tracking configuration returned by the storefront `store` query.
+ */
+interface BrowserTrackingConfig {
+    gtm: GtmBrowserTrackingConfig;
+}
+interface StoreAnalyticsConfig {
+    enabled: boolean;
+    dispatchOnUnknownConsent: boolean;
+    gtm: GtmBrowserTrackingConfig;
+}
+interface Store {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    currency: string;
+    timezone: string;
+    logoUrl: string | null;
+    contactEmail: string | null;
+    contactPhone: string | null;
+    trackingDispatchOnUnknownConsent: boolean;
+    browserTrackingConfig: BrowserTrackingConfig;
+    analytics: StoreAnalyticsConfig;
+    socialLinks: SocialLinks;
+}
+interface PaymentInstructions {
+    bankAccount: string;
+    recipientName: string;
+    referenceNumber: string;
+    ipsQrCodeBase64: string;
+    expiresAt: string;
+}
+interface OrderItem {
+    id: string;
+    productTitle: string;
+    variantTitle: string | null;
+    sku: string | null;
+    quantity: number;
+    unitPrice: number;
+    totalPrice: number;
+}
+interface Order {
+    id: string;
+    orderNumber: string;
+    email: string | null;
+    phone: string | null;
+    status: string;
+    shippingAddress: Address | null;
+    subtotal: number;
+    total: number;
+    note: string | null;
+    items: OrderItem[];
+    paymentInstructions: PaymentInstructions | null;
+    createdAt: string;
+}
+interface Customer {
+    id: string;
+    name: string | null;
+    email: string;
+    emailVerified: boolean;
+}
+interface CustomerAddress {
+    id: string;
+    label: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    addressLine1: string;
+    addressLine2: string | null;
+    city: string;
+    zip: string | null;
+    phone: string | null;
+    isDefault: boolean;
+    createdAt: string;
+}
+interface CustomerAddressInput {
+    label?: string;
+    firstName?: string;
+    lastName?: string;
+    addressLine1: string;
+    addressLine2?: string;
+    city: string;
+    zip?: string;
+    phone?: string;
+    isDefault?: boolean;
+}
+interface CustomerAddressUpdateInput {
+    label?: string;
+    firstName?: string;
+    lastName?: string;
+    addressLine1?: string;
+    addressLine2?: string;
+    city?: string;
+    zip?: string;
+    phone?: string;
+    isDefault?: boolean;
+}
+interface CustomerUpdateInput {
+    name?: string;
+    email?: string;
+    currentPassword?: string;
+    newPassword?: string;
+}
+interface CustomerOrderItem {
+    id: string;
+    productTitle: string;
+    variantTitle: string | null;
+    sku: string | null;
+    quantity: number;
+    unitPrice: number;
+    totalPrice: number;
+}
+interface CustomerOrder {
+    id: string;
+    orderNumber: string;
+    status: string;
+    email: string;
+    phone: string | null;
+    subtotal: number;
+    total: number;
+    note: string | null;
+    items: CustomerOrderItem[];
+    createdAt: string;
+}
+
+export type { Address, AppliedDiscount, AppliedPromoCode, AvailablePaymentMethod, BrowserTrackingConfig, BulletListDetailSection, Cart, CartItem, CartStatus, Category, CheckoutData, Collection, CollectionSortOrder, CollectionType, Customer, CustomerAddress, CustomerAddressInput, CustomerAddressUpdateInput, CustomerOrder, CustomerOrderItem, CustomerUpdateInput, DetailSection, DisplayIntent, FlatCategory, GtmBrowserTrackingConfig, Order, OrderItem, PageInfo, PaginatedResult, PaymentInstructions, Product, ProductFilter, ProductImage, ProductOption, ProductOptionValue, ProductSortKey, ProductVariant, QuantityPricingTier, ResolvedStorefrontAnalyticsConfig, ResolvedStorefrontInitConfig, RichTextDetailSection, SectionType, ShippingRate, SocialLinks, StorageAdapter, Store, StoreAnalyticsConfig, StorefrontAnalyticsInitConfig, StorefrontClientConfig, StorefrontInitOptions, StorefrontResult, TableDetailSection, Tag, WeightUnit };