@doswiftly/storefront-sdk 4.0.0

package/dist/core/cart/cart-client.js

@@ -0,0 +1,89 @@
+/**
+ * CartClient — plain async API for cart operations (no React, no React Query).
+ *
+ * Wraps StorefrontClient.mutate/query with typed operations.
+ * Auto-throws on userErrors via assertNoUserErrors.
+ *
+ * @example
+ * ```typescript
+ * const cartClient = new CartClient(storefrontClient);
+ *
+ * const cart = await cartClient.create();
+ * const updated = await cartClient.addItem(cart.id, [
+ *   { merchandiseId: 'variant-123', quantity: 1 }
+ * ]);
+ * ```
+ */
+import { assertNoUserErrors } from '../helpers/assert-no-user-errors';
+import { CART_QUERY, CART_CREATE, CART_LINES_ADD, CART_LINES_UPDATE, CART_LINES_REMOVE, CART_DISCOUNT_CODES_UPDATE, CART_NOTE_UPDATE, CART_BUYER_IDENTITY_UPDATE, } from '../operations/cart';
+export class CartClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Fetch existing cart by ID.
+     * Returns null if cart doesn't exist or has expired.
+     */
+    async get(cartId) {
+        const data = await this.client.query(CART_QUERY, { id: cartId });
+        return data.cart;
+    }
+    /**
+     * Create a new cart, optionally with initial lines.
+     */
+    async create(input) {
+        const data = await this.client.mutate(CART_CREATE, { input: input ?? {} });
+        assertNoUserErrors(data.cartCreate);
+        return data.cartCreate.cart;
+    }
+    /**
+     * Add line items to an existing cart.
+     */
+    async addItems(cartId, lines) {
+        const data = await this.client.mutate(CART_LINES_ADD, { cartId, lines });
+        assertNoUserErrors(data.cartLinesAdd);
+        return data.cartLinesAdd.cart;
+    }
+    /**
+     * Update line items (quantity, attributes).
+     */
+    async updateItems(cartId, lines) {
+        const data = await this.client.mutate(CART_LINES_UPDATE, { cartId, lines });
+        assertNoUserErrors(data.cartLinesUpdate);
+        return data.cartLinesUpdate.cart;
+    }
+    /**
+     * Remove line items by their line IDs.
+     */
+    async removeItems(cartId, lineIds) {
+        const data = await this.client.mutate(CART_LINES_REMOVE, { cartId, lineIds });
+        assertNoUserErrors(data.cartLinesRemove);
+        return data.cartLinesRemove.cart;
+    }
+    /**
+     * Update discount codes (replaces all existing codes).
+     * Pass empty array to clear discounts.
+     */
+    async updateDiscountCodes(cartId, discountCodes) {
+        const data = await this.client.mutate(CART_DISCOUNT_CODES_UPDATE, { cartId, discountCodes });
+        assertNoUserErrors(data.cartDiscountCodesUpdate);
+        return data.cartDiscountCodesUpdate.cart;
+    }
+    /**
+     * Update cart note / gift message.
+     */
+    async updateNote(cartId, note) {
+        const data = await this.client.mutate(CART_NOTE_UPDATE, { cartId, note });
+        assertNoUserErrors(data.cartNoteUpdate);
+        return data.cartNoteUpdate.cart;
+    }
+    /**
+     * Update buyer identity (email, phone, country, customer link).
+     */
+    async updateBuyerIdentity(cartId, buyerIdentity) {
+        const data = await this.client.mutate(CART_BUYER_IDENTITY_UPDATE, { cartId, buyerIdentity });
+        assertNoUserErrors(data.cartBuyerIdentityUpdate);
+        return data.cartBuyerIdentityUpdate.cart;
+    }
+}

package/dist/core/cart/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Cart types — manual (no codegen).
+ *
+ * These match the backend storefront-graphql Cart type.
+ */
+export interface Money {
+    amount: string;
+    currencyCode: string;
+}
+export interface CartCost {
+    totalAmount: Money;
+    subtotalAmount: Money;
+    totalTaxAmount: Money | null;
+    totalDutyAmount: Money | null;
+}
+export interface CartLineCost {
+    totalAmount: Money;
+    amountPerQuantity: Money;
+    compareAtAmountPerQuantity: Money | null;
+}
+export interface CartLineMerchandise {
+    id: string;
+    title: string;
+    sku: string | null;
+    image: {
+        url: string;
+        altText: string | null;
+    } | null;
+    price: Money;
+    compareAtPrice: Money | null;
+}
+export interface CartLine {
+    id: string;
+    quantity: number;
+    merchandise: CartLineMerchandise;
+    cost: CartLineCost;
+    attributes: Array<{
+        key: string;
+        value: string;
+    }>;
+    productId: string;
+    productTitle: string;
+    productHandle: string;
+}
+export interface CartDiscountCode {
+    code: string;
+    applicable: boolean;
+}
+export interface CartDiscountAllocation {
+    discountedAmount: Money;
+}
+export interface CartBuyerIdentity {
+    email: string | null;
+    phone: string | null;
+    countryCode: string | null;
+}
+export interface Cart {
+    id: string;
+    checkoutUrl: string | null;
+    totalQuantity: number;
+    note: string | null;
+    createdAt: string;
+    updatedAt: string;
+    cost: CartCost;
+    lines: {
+        edges: Array<{
+            node: CartLine;
+        }>;
+    };
+    buyerIdentity: CartBuyerIdentity | null;
+    discountCodes: CartDiscountCode[];
+    discountAllocations: CartDiscountAllocation[];
+    attributes: Array<{
+        key: string;
+        value: string;
+    }>;
+}
+export interface CartLineInput {
+    merchandiseId: string;
+    quantity?: number;
+    attributes?: Array<{
+        key: string;
+        value: string;
+    }>;
+}
+export interface CartLineUpdateInput {
+    id: string;
+    quantity: number;
+    attributes?: Array<{
+        key: string;
+        value: string;
+    }>;
+}
+export interface CartCreateInput {
+    lines?: CartLineInput[];
+    buyerIdentity?: CartBuyerIdentityInput;
+    discountCodes?: string[];
+    note?: string;
+    attributes?: Array<{
+        key: string;
+        value: string;
+    }>;
+}
+export interface CartBuyerIdentityInput {
+    email?: string;
+    phone?: string;
+    countryCode?: string;
+    customerId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/cart/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/cart/types.ts"],"names":[],"mappings":"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"}

package/dist/core/cart/types.js

@@ -0,0 +1,6 @@
+/**
+ * Cart types — manual (no codegen).
+ *
+ * These match the backend storefront-graphql Cart type.
+ */
+export {};

package/dist/core/client/compose.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Compose middleware chain using reduceRight (Hydrogen pattern).
+ *
+ * Middleware execute in order: first registered runs first.
+ * Each can modify request, modify response, retry, or short-circuit.
+ */
+import type { Middleware, ExecuteFn } from './types';
+export declare function compose(middlewares: Middleware[], execute: ExecuteFn): ExecuteFn;
+//# sourceMappingURL=compose.d.ts.map

package/dist/core/client/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../../src/core/client/compose.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAErD,wBAAgB,OAAO,CAAC,WAAW,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,SAAS,GAAG,SAAS,CAKhF"}

package/dist/core/client/compose.js

@@ -0,0 +1,9 @@
+/**
+ * Compose middleware chain using reduceRight (Hydrogen pattern).
+ *
+ * Middleware execute in order: first registered runs first.
+ * Each can modify request, modify response, retry, or short-circuit.
+ */
+export function compose(middlewares, execute) {
+    return middlewares.reduceRight((next, mw) => (req) => mw(req, next), execute);
+}

package/dist/core/client/create-client.d.ts

@@ -0,0 +1,15 @@
+/**
+ * createStorefrontClient — transport factory (Hydrogen pattern).
+ *
+ * Creates a framework-agnostic GraphQL client with:
+ * - Middleware pipeline (composable, lazy)
+ * - Request deduplication (same-tick queries)
+ * - TypedDocumentString support (Saleor/client-preset)
+ * - Plain string queries (for custom operations)
+ * - Debug mode
+ *
+ * 0 runtime dependencies.
+ */
+import type { StorefrontClientConfig, StorefrontClient } from './types';
+export declare function createStorefrontClient(config: StorefrontClientConfig): StorefrontClient;
+//# sourceMappingURL=create-client.d.ts.map

package/dist/core/client/create-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-client.d.ts","sourceRoot":"","sources":["../../../src/core/client/create-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,gBAAgB,EAKjB,MAAM,SAAS,CAAC;AAOjB,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,sBAAsB,GAAG,gBAAgB,CAqGvF"}

package/dist/core/client/create-client.js

@@ -0,0 +1,85 @@
+/**
+ * createStorefrontClient — transport factory (Hydrogen pattern).
+ *
+ * Creates a framework-agnostic GraphQL client with:
+ * - Middleware pipeline (composable, lazy)
+ * - Request deduplication (same-tick queries)
+ * - TypedDocumentString support (Saleor/client-preset)
+ * - Plain string queries (for custom operations)
+ * - Debug mode
+ *
+ * 0 runtime dependencies.
+ */
+import { createExecute } from './execute';
+import { compose } from './compose';
+import { dedupe } from './dedupe';
+import { hashQuery } from './hash';
+import { getOperationName } from './operation-name';
+export function createStorefrontClient(config) {
+    const { apiUrl, shopSlug, defaultHeaders = {}, middleware: initialMiddleware = [], fetch: customFetch = globalThis.fetch, debug = false, } = config;
+    const endpoint = `${apiUrl.replace(/\/$/, '')}/storefront/graphql`;
+    // Mutable middleware list — use() adds to it, invalidates compiled pipeline
+    const middlewares = [...initialMiddleware];
+    let compiledPipeline = null;
+    // Create the innermost execute function (native fetch)
+    const innerExecute = createExecute({ endpoint, fetch: customFetch, debug });
+    /**
+     * Get or build the compiled middleware pipeline (lazy).
+     * Rebuilt on first call and after use() is called.
+     */
+    function getPipeline() {
+        if (!compiledPipeline) {
+            compiledPipeline = middlewares.length > 0
+                ? compose(middlewares, innerExecute)
+                : innerExecute;
+        }
+        return compiledPipeline;
+    }
+    /**
+     * Resolve query string from TypedDocumentString or plain string.
+     */
+    function resolveQuery(document) {
+        return typeof document === 'string' ? document : document.toString();
+    }
+    /**
+     * Core request execution — shared by query() and mutate().
+     */
+    async function request(document, variables, isMutation = false, cache) {
+        const query = resolveQuery(document);
+        const operationName = getOperationName(query);
+        const pipeline = getPipeline();
+        const headers = {
+            'X-Shop-Slug': shopSlug,
+            ...defaultHeaders,
+        };
+        if (operationName !== 'anonymous') {
+            headers['X-Operation-Name'] = operationName;
+        }
+        const graphqlRequest = {
+            query,
+            variables,
+            operationName,
+            headers,
+            isMutation,
+            cache,
+        };
+        // Dedupe queries (not mutations) in the same tick
+        const executeFn = () => pipeline(graphqlRequest);
+        const response = isMutation
+            ? await executeFn()
+            : await dedupe(hashQuery(query, variables), executeFn);
+        return response.data;
+    }
+    return {
+        query(document, variables, cache) {
+            return request(document, variables, false, cache);
+        },
+        mutate(document, variables) {
+            return request(document, variables, true);
+        },
+        use(middleware) {
+            middlewares.push(middleware);
+            compiledPipeline = null; // Invalidate — rebuild on next request
+        },
+    };
+}

package/dist/core/client/dedupe.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Request deduplication — identical queries in the same tick share one fetch.
+ *
+ * Key = hashQuery(query, variables). Only applies to queries, not mutations.
+ */
+export declare function dedupe<T>(key: string, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=dedupe.d.ts.map

package/dist/core/client/dedupe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../../../src/core/client/dedupe.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAUvE"}

package/dist/core/client/dedupe.js

@@ -0,0 +1,16 @@
+/**
+ * Request deduplication — identical queries in the same tick share one fetch.
+ *
+ * Key = hashQuery(query, variables). Only applies to queries, not mutations.
+ */
+const pending = new Map();
+export function dedupe(key, fn) {
+    const existing = pending.get(key);
+    if (existing)
+        return existing;
+    const promise = fn().finally(() => {
+        pending.delete(key);
+    });
+    pending.set(key, promise);
+    return promise;
+}

package/dist/core/client/execute.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Native fetch transport — 0 runtime dependencies.
+ *
+ * Sends GraphQL POST request, parses response, returns typed GraphQLResponse.
+ * Error normalization is handled by error middleware, NOT here.
+ */
+import type { GraphQLRequest, GraphQLResponse } from './types';
+export interface ExecuteConfig {
+    /** GraphQL endpoint URL */
+    endpoint: string;
+    /** Custom fetch implementation */
+    fetch: typeof globalThis.fetch;
+    /** Enable debug logging */
+    debug: boolean;
+}
+/**
+ * Create the innermost execute function for the middleware pipeline.
+ */
+export declare function createExecute(config: ExecuteConfig): (request: GraphQLRequest) => Promise<GraphQLResponse>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/core/client/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../src/core/client/execute.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAoB,MAAM,SAAS,CAAC;AAEjF,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAC/B,2BAA2B;IAC3B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,IAGnB,SAAS,cAAc,KAAG,OAAO,CAAC,eAAe,CAAC,CA6CjF"}

package/dist/core/client/execute.js

@@ -0,0 +1,48 @@
+/**
+ * Native fetch transport — 0 runtime dependencies.
+ *
+ * Sends GraphQL POST request, parses response, returns typed GraphQLResponse.
+ * Error normalization is handled by error middleware, NOT here.
+ */
+/**
+ * Create the innermost execute function for the middleware pipeline.
+ */
+export function createExecute(config) {
+    const { endpoint, fetch: fetchFn, debug } = config;
+    return async function execute(request) {
+        const { query, variables, headers, signal, operationName } = request;
+        if (debug) {
+            console.log('[StorefrontSDK]', operationName ?? 'request', { variables });
+        }
+        const body = { query };
+        if (variables && Object.keys(variables).length > 0) {
+            body.variables = variables;
+        }
+        if (operationName) {
+            body.operationName = operationName;
+        }
+        const response = await fetchFn(endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+                ...headers,
+            },
+            body: JSON.stringify(body),
+            signal,
+        });
+        const json = await response.json();
+        if (debug) {
+            console.log('[StorefrontSDK]', operationName ?? 'response', {
+                status: response.status,
+                hasErrors: !!json.errors?.length,
+            });
+        }
+        return {
+            data: json.data,
+            errors: json.errors,
+            status: response.status,
+            headers: response.headers,
+        };
+    };
+}

package/dist/core/client/hash.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Stable query hashing for request deduplication.
+ *
+ * Sorts object keys so `{a:1,b:2}` and `{b:2,a:1}` produce the same hash.
+ */
+export declare function hashQuery(query: string, variables?: Record<string, unknown>): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/core/client/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/core/client/hash.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAIpF"}

package/dist/core/client/hash.js

@@ -0,0 +1,21 @@
+/**
+ * Stable query hashing for request deduplication.
+ *
+ * Sorts object keys so `{a:1,b:2}` and `{b:2,a:1}` produce the same hash.
+ */
+function stableStringify(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return '[' + value.map(stableStringify).join(',') + ']';
+    }
+    const keys = Object.keys(value).sort();
+    return '{' + keys.map(k => JSON.stringify(k) + ':' + stableStringify(value[k])).join(',') + '}';
+}
+export function hashQuery(query, variables) {
+    const queryPart = query.trim();
+    const varsPart = variables ? stableStringify(variables) : '';
+    return queryPart + '::' + varsPart;
+}

package/dist/core/client/operation-name.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Auto-extract operation name from a GraphQL query string.
+ *
+ * Used for: X-Operation-Name header (debugging), cache tags, logging.
+ */
+export declare function getOperationName(query: string): string;
+//# sourceMappingURL=operation-name.d.ts.map

package/dist/core/client/operation-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-name.d.ts","sourceRoot":"","sources":["../../../src/core/client/operation-name.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGtD"}

package/dist/core/client/operation-name.js

@@ -0,0 +1,10 @@
+/**
+ * Auto-extract operation name from a GraphQL query string.
+ *
+ * Used for: X-Operation-Name header (debugging), cache tags, logging.
+ */
+const OPERATION_RE = /(?:query|mutation|subscription)\s+(\w+)/;
+export function getOperationName(query) {
+    const match = query.match(OPERATION_RE);
+    return match?.[1] ?? 'anonymous';
+}

package/dist/core/client/types.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Core types for Storefront SDK transport layer.
+ *
+ * Framework-agnostic — no React, no Zustand, 0 runtime dependencies.
+ */
+/**
+ * A branded string carrying result & variable types.
+ * Produced by graphql-codegen client-preset with `documentMode: 'string'`.
+ *
+ * SDK also accepts plain strings — TypedDocumentString is purely for DX.
+ */
+export declare class TypedDocumentString<TResult = unknown, TVariables = unknown> extends String {
+    __meta__?: {
+        hash: string;
+    } | undefined;
+    /** Type-level brand — never used at runtime */
+    __apiType?: (variables: TVariables) => TResult;
+    constructor(value: string, __meta__?: {
+        hash: string;
+    } | undefined);
+    toString(): string;
+}
+export interface GraphQLRequest {
+    /** GraphQL query or mutation string */
+    query: string;
+    /** Operation variables */
+    variables?: Record<string, unknown>;
+    /** Operation name (auto-extracted if omitted) */
+    operationName?: string;
+    /** Request headers (merged: default < middleware < request) */
+    headers: Record<string, string>;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Whether this is a mutation (affects retry, cache) */
+    isMutation: boolean;
+    /** Cache strategy override */
+    cache?: CacheStrategy;
+}
+export interface GraphQLResponse<T = unknown> {
+    /** Parsed response data */
+    data: T;
+    /** GraphQL errors (if any) */
+    errors?: GraphQLErrorInfo[];
+    /** HTTP status code */
+    status: number;
+    /** Raw response headers */
+    headers: Headers;
+}
+export interface GraphQLErrorInfo {
+    message: string;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: Array<string | number>;
+    extensions?: Record<string, unknown>;
+}
+export interface UserError {
+    message: string;
+    field?: string[];
+    code?: string;
+}
+/**
+ * Execute function — the innermost (or next) handler in the pipeline.
+ */
+export type ExecuteFn = (request: GraphQLRequest) => Promise<GraphQLResponse>;
+/**
+ * Middleware function — receives the request and the next handler.
+ *
+ * Can modify request, modify response, short-circuit, retry, etc.
+ *
+ * @example
+ * ```typescript
+ * const authMiddleware: Middleware = (req, next) => {
+ *   req.headers['Authorization'] = `Bearer ${getToken()}`;
+ *   return next(req);
+ * };
+ * ```
+ */
+export type Middleware = (request: GraphQLRequest, next: ExecuteFn) => Promise<GraphQLResponse>;
+export interface CacheOptions {
+    /** Max age in seconds */
+    maxAge: number;
+    /** Stale-while-revalidate in seconds */
+    staleWhileRevalidate?: number;
+    /** Cache mode */
+    mode: 'public' | 'private' | 'no-store';
+    /** Cache tags (for Next.js revalidateTag) */
+    tags?: string[];
+}
+export type CacheStrategy = CacheOptions;
+export interface StorefrontClientConfig {
+    /** GraphQL API URL (e.g. 'https://api.doswiftly.pl') */
+    apiUrl: string;
+    /** Shop slug for multi-tenant routing */
+    shopSlug: string;
+    /** Default headers for all requests */
+    defaultHeaders?: Record<string, string>;
+    /** Middleware pipeline */
+    middleware?: Middleware[];
+    /** Custom fetch implementation (polyfill, test mocks, edge) */
+    fetch?: typeof globalThis.fetch;
+    /** Enable debug logging (request/response in dev) */
+    debug?: boolean;
+}
+export interface StorefrontClient {
+    /**
+     * Execute a typed GraphQL query.
+     *
+     * Accepts TypedDocumentString (from codegen) or plain string.
+     */
+    query<T = unknown, V = Record<string, unknown>>(document: TypedDocumentString<T, V> | string, variables?: V, cache?: CacheStrategy): Promise<T>;
+    /**
+     * Execute a typed GraphQL mutation.
+     *
+     * Mutations are never cached and never retried by retry middleware.
+     */
+    mutate<T = unknown, V = Record<string, unknown>>(document: TypedDocumentString<T, V> | string, variables?: V): Promise<T>;
+    /**
+     * Add middleware to the pipeline (imperative API).
+     *
+     * Invalidates the compiled pipeline — next request re-composes.
+     */
+    use(middleware: Middleware): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/client/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/client/types.ts"],"names":[],"mappings":"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"}

package/dist/core/client/types.js

@@ -0,0 +1,26 @@
+/**
+ * Core types for Storefront SDK transport layer.
+ *
+ * Framework-agnostic — no React, no Zustand, 0 runtime dependencies.
+ */
+// ---------------------------------------------------------------------------
+// TypedDocumentString (Saleor / client-preset pattern)
+// ---------------------------------------------------------------------------
+/**
+ * A branded string carrying result & variable types.
+ * Produced by graphql-codegen client-preset with `documentMode: 'string'`.
+ *
+ * SDK also accepts plain strings — TypedDocumentString is purely for DX.
+ */
+export class TypedDocumentString extends String {
+    __meta__;
+    /** Type-level brand — never used at runtime */
+    __apiType;
+    constructor(value, __meta__) {
+        super(value);
+        this.__meta__ = __meta__;
+    }
+    toString() {
+        return this.valueOf();
+    }
+}