@curless/shopify-storefront 0.1.0

package/dist/card.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.generated.js","sourceRoot":"","sources":["../src/card.generated.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,2EAA2E;AAC3E,gFAAgF;AAChF,4DAA4D;AAC5D,MAAM,CAAC,MAAM,eAAe,GAAW,MAAM,CAAC,IAAI,CAChD,0tsdAA0tsd,EAC1tsd,QAAQ,CACT,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC"}

package/dist/catalog-registry.d.ts

@@ -0,0 +1,44 @@
+import type { ShopifyConfig } from '@curless/shopify-adapter';
+import { Catalog } from './catalog.js';
+export type RegistryOptions = {
+    /** How often each shop's catalogue refreshes. */
+    refreshMs: number;
+    /** Drop a shop's catalogue after this long without a request. */
+    idleMs?: number;
+    /** Hard ceiling on resident catalogues; the least recently used goes first. */
+    maxShops?: number;
+    /** Injected so tests do not depend on the clock. */
+    now?: () => number;
+};
+export declare class CatalogRegistry {
+    private readonly resolveConfig;
+    private readonly opts;
+    private readonly entries;
+    private readonly idleMs;
+    private readonly maxShops;
+    private readonly now;
+    constructor(resolveConfig: (shop: string) => Promise<ShopifyConfig | null>, opts: RegistryOptions);
+    /** Resident shops — for a status page, and for the tests below. */
+    get size(): number;
+    /**
+     * The catalogue for one shop, created on first use.
+     *
+     * Sweeping on access rather than on a timer of its own: the work is
+     * proportional to traffic, and a registry nobody is using does not need to
+     * wake up to discover it is idle.
+     */
+    for(shop: string): Catalog;
+    /**
+     * Stop serving a shop — uninstall, and shop/redact.
+     *
+     * The timer is stopped BEFORE the entry is dropped. Dropping first would
+     * leave a Catalog nothing references but whose interval still fires, which is
+     * precisely the request to a revoked token that must not happen.
+     */
+    forget(shop: string): void;
+    /** Stop everything — for a clean shutdown. */
+    stopAll(): void;
+    private sweep;
+    private evictOverflow;
+}
+//# sourceMappingURL=catalog-registry.d.ts.map

package/dist/catalog-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-registry.d.ts","sourceRoot":"","sources":["../src/catalog-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAiB9D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAIvC,MAAM,MAAM,eAAe,GAAG;IAC5B,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,CAAC;AAEF,qBAAa,eAAe;IAOxB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAGhB,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,EAC9D,IAAI,EAAE,eAAe;IAOxC,mEAAmE;IACnE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;OAMG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAkB1B;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQ1B,8CAA8C;IAC9C,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,KAAK;IAUb,OAAO,CAAC,aAAa;CAgBtB"}

package/dist/catalog-registry.js

@@ -0,0 +1,105 @@
+// One catalogue per shop, for the listed public app.
+//
+// A branded deployment has exactly one, built at boot and refreshed for the
+// life of the process. A listed app cannot: it serves whichever shops have
+// installed it, it learns of a new one mid-flight, and it must stop serving one
+// the moment that merchant uninstalls.
+//
+// Two things go wrong if this is just a Map.
+//
+//   • A shop that uninstalls keeps its refresh timer, so we go on calling THAT
+//     merchant's Shopify with a token they revoked — forever, for someone who
+//     is no longer a customer. Eviction has to stop the timer, not just drop
+//     the reference.
+//   • Every shop holds a full product snapshot. A few hundred merchants is a
+//     few hundred catalogues resident at once, and nothing ever released the
+//     ones nobody has asked about in a week.
+import { Catalog } from './catalog.js';
+export class CatalogRegistry {
+    resolveConfig;
+    opts;
+    entries = new Map();
+    idleMs;
+    maxShops;
+    now;
+    constructor(resolveConfig, opts) {
+        this.resolveConfig = resolveConfig;
+        this.opts = opts;
+        this.idleMs = opts.idleMs ?? 6 * 60 * 60 * 1000;
+        this.maxShops = opts.maxShops ?? 500;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /** Resident shops — for a status page, and for the tests below. */
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * The catalogue for one shop, created on first use.
+     *
+     * Sweeping on access rather than on a timer of its own: the work is
+     * proportional to traffic, and a registry nobody is using does not need to
+     * wake up to discover it is idle.
+     */
+    for(shop) {
+        const key = shop.toLowerCase();
+        this.sweep();
+        const hit = this.entries.get(key);
+        if (hit) {
+            hit.lastUsed = this.now();
+            return hit.catalog;
+        }
+        const catalog = new Catalog(() => this.resolveConfig(key), (m) => console.log(`[catalog ${key}] ${m}`));
+        catalog.start(this.opts.refreshMs);
+        this.entries.set(key, { catalog, lastUsed: this.now() });
+        this.evictOverflow();
+        return catalog;
+    }
+    /**
+     * Stop serving a shop — uninstall, and shop/redact.
+     *
+     * The timer is stopped BEFORE the entry is dropped. Dropping first would
+     * leave a Catalog nothing references but whose interval still fires, which is
+     * precisely the request to a revoked token that must not happen.
+     */
+    forget(shop) {
+        const key = shop.toLowerCase();
+        const hit = this.entries.get(key);
+        if (!hit)
+            return;
+        hit.catalog.stop();
+        this.entries.delete(key);
+    }
+    /** Stop everything — for a clean shutdown. */
+    stopAll() {
+        for (const [, e] of this.entries)
+            e.catalog.stop();
+        this.entries.clear();
+    }
+    sweep() {
+        const cutoff = this.now() - this.idleMs;
+        for (const [key, e] of this.entries) {
+            if (e.lastUsed < cutoff) {
+                e.catalog.stop();
+                this.entries.delete(key);
+            }
+        }
+    }
+    evictOverflow() {
+        while (this.entries.size > this.maxShops) {
+            let oldestKey = null;
+            let oldest = Number.POSITIVE_INFINITY;
+            for (const [key, e] of this.entries) {
+                if (e.lastUsed < oldest) {
+                    oldest = e.lastUsed;
+                    oldestKey = key;
+                }
+            }
+            if (oldestKey === null)
+                return;
+            const victim = this.entries.get(oldestKey);
+            victim?.catalog.stop();
+            this.entries.delete(oldestKey);
+        }
+    }
+}
+//# sourceMappingURL=catalog-registry.js.map

package/dist/catalog-registry.js.map

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

package/dist/catalog.d.ts

@@ -0,0 +1,51 @@
+import { type ProductVariant, type ShopifyConfig, type ShopifyDiscount, type ShopifyProduct } from '@curless/shopify-adapter';
+export type CatalogSnapshot = {
+    products: ShopifyProduct[];
+    /** When this snapshot was successfully loaded. null = never loaded. */
+    loadedAt: Date | null;
+    /** Set when the LAST attempt failed — the snapshot is then stale, not absent. */
+    lastError?: string;
+    /**
+     * The shop's live automatic discounts — "Buy 2 get 5% OFF", "Gift over $66".
+     * They live nowhere near a product, so a catalogue that only reads products
+     * quotes a price the buyer beats at checkout and never mentions the offer that
+     * would have made them buy two.
+     */
+    discounts: ShopifyDiscount[];
+    /**
+     * Why there are none, when the reason is not "the shop is running none".
+     * `read_discounts` is granted at INSTALL, so until the merchant reinstalls the
+     * query is refused — and "we cannot see them" has to be distinguishable from
+     * "there are none", or nobody knows to ask them to reinstall.
+     */
+    discountsBlocked?: string;
+};
+export declare class Catalog {
+    private readonly resolveConfig;
+    private readonly log;
+    private snapshot;
+    private inFlight;
+    private variants;
+    private upstream;
+    constructor(resolveConfig: () => Promise<ShopifyConfig | null>, log?: (msg: string) => void);
+    get current(): CatalogSnapshot;
+    /** Products, newest snapshot. Empty only before the first successful load. */
+    list(): ShopifyProduct[];
+    byHandleOrTitle(q: string): ShopifyProduct | undefined;
+    refresh(): Promise<void>;
+    /** Every variant of one product, paginated to completion, cached briefly. */
+    variantsFor(handle: string, now?: number): Promise<ProductVariant[]>;
+    private timer;
+    /** Refresh now, then on an interval. Never throws — boot must not depend on Shopify. */
+    start(intervalMs: number): void;
+    /**
+     * Stop refreshing.
+     *
+     * A single-shop deployment never needs this — the process owns one catalogue
+     * for its whole life. A multi-tenant one does: when a merchant uninstalls,
+     * an unstoppable timer keeps calling THEIR Shopify with a token they revoked,
+     * forever, for a shop that is no longer a customer.
+     */
+    stop(): void;
+}
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AASA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,cAAc,EAKpB,MAAM,0BAA0B,CAAC;AAGlC,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AA2BF,qBAAa,OAAO;IAchB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAdtB,OAAO,CAAC,QAAQ,CAAoE;IACpF,OAAO,CAAC,QAAQ,CAA8B;IAG9C,OAAO,CAAC,QAAQ,CAA6D;IAE7E,OAAO,CAAC,QAAQ,CAAoD;gBAOjD,aAAa,EAAE,MAAM,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,EAClD,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAA2C;IAGpF,IAAI,OAAO,IAAI,eAAe,CAE7B;IAED,8EAA8E;IAC9E,IAAI,IAAI,cAAc,EAAE;IAIxB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAYhD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmE9B,6EAA6E;IACvE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAyBtF,OAAO,CAAC,KAAK,CAA+C;IAE5D,wFAAwF;IACxF,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAQ/B;;;;;;;OAOG;IACH,IAAI,IAAI,IAAI;CAIb"}

package/dist/catalog.js

@@ -0,0 +1,189 @@
+// The Moody catalog, held in memory and refreshed in the background.
+//
+// Two properties matter more than freshness here:
+//
+//   • A tool call must never wait on Shopify. The buyer is mid-conversation;
+//     a 2-second catalog fetch inside "show me the vivid ones" is felt.
+//   • A failed refresh must never empty the shelf. An empty catalog is not a
+//     degraded store, it is a closed one — so a refresh that fails keeps the
+//     last good snapshot and says so.
+import { activeDiscounts, fetchProductVariants, fetchShopifyDiscounts, fetchShopifyProducts, } from '@curless/shopify-adapter';
+import { RateLimiter } from './rate-limit.js';
+// A product's variants are NOT in the snapshot: a pair of lenses is Left ×
+// Right, 676 rows, and 382 of those is a quarter-million objects held to answer
+// "what do you sell". They are fetched for the one product a buyer is looking
+// at, and remembered briefly — looking at a lens and then buying it is two calls
+// for the same rows.
+const VARIANT_TTL_MS = 5 * 60_000;
+const VARIANT_CACHE_MAX = 50;
+// A GLOBAL ceiling on cache misses, in addition to whatever per-IP limit sits in
+// front of the endpoint.
+//
+// Per-IP is the wrong unit here, because the resource being spent is not ours —
+// it is the MERCHANT's Shopify API quota. One uncached `variantsFor` costs up to
+// three Admin API calls (676 variants at 250 a page), the cache holds 50 of 382
+// products, and cycling handles defeats it by design. At 60 calls a minute per
+// address that is 180 Admin calls a minute from ONE caller, and nothing stops
+// the second caller. Exhausting that quota does not degrade us; it degrades the
+// merchant's own storefront and their other apps, which is a worse outcome than
+// this connector being slow.
+//
+// 90 a minute leaves ample room for real shoppers — a shopper opens a handful of
+// lenses, and the second look at one is free — while capping the whole service's
+// draw on the merchant at well under Shopify's budget.
+const VARIANT_FETCHES_PER_MIN = 90;
+export class Catalog {
+    resolveConfig;
+    log;
+    snapshot = { products: [], loadedAt: null, discounts: [] };
+    inFlight = null;
+    // Per INSTANCE, not per module: a module-level cache outlives whatever created
+    // it, which in tests means one case seeing another's stock levels.
+    variants = new Map();
+    // One bucket for the whole service, not per caller — see VARIANT_FETCHES_PER_MIN.
+    upstream = new RateLimiter(VARIANT_FETCHES_PER_MIN, 60_000);
+    // The config is RESOLVED per refresh, not captured at construction: the token
+    // arrives when the merchant installs the app, which may be long after this
+    // process started. Null means "not connected yet" — a state to report, not to
+    // crash on.
+    constructor(resolveConfig, log = (m) => console.log(`[catalog] ${m}`)) {
+        this.resolveConfig = resolveConfig;
+        this.log = log;
+    }
+    get current() {
+        return this.snapshot;
+    }
+    /** Products, newest snapshot. Empty only before the first successful load. */
+    list() {
+        return this.snapshot.products;
+    }
+    byHandleOrTitle(q) {
+        const norm = (s) => s.trim().toLowerCase();
+        const n = norm(q);
+        return (this.snapshot.products.find((p) => norm(p.handle) === n || norm(p.title) === n) ??
+            this.snapshot.products.find((p) => norm(p.title).includes(n) || norm(p.handle).includes(n)));
+    }
+    // Concurrent callers share one fetch: on boot every tool call would otherwise
+    // start its own, and Shopify would rate-limit us for asking the same question
+    // ten times.
+    async refresh() {
+        if (this.inFlight)
+            return this.inFlight;
+        this.inFlight = (async () => {
+            try {
+                const config = await this.resolveConfig();
+                if (!config) {
+                    this.snapshot = {
+                        ...this.snapshot,
+                        lastError: 'not connected — the merchant has not installed the app yet',
+                    };
+                    return;
+                }
+                const products = await fetchShopifyProducts(config, fetch, (m) => this.log(m));
+                if (products.length === 0) {
+                    // Shopify answered, with nothing. Could be a real empty store, could
+                    // be a scope we lost — either way, do not replace a shelf that has
+                    // stock on it with one that has none.
+                    this.snapshot = {
+                        ...this.snapshot,
+                        lastError: 'shopify returned no products',
+                    };
+                    this.log('refresh returned 0 products — keeping the previous snapshot');
+                    return;
+                }
+                // Discounts are read alongside, and are ALLOWED to fail: they need a
+                // scope the merchant grants at install time, and a storefront that
+                // stopped selling because it could not read a promotion would be a
+                // spectacular own goal.
+                const promo = await fetchShopifyDiscounts(config).catch(() => ({ ok: false, reason: 'failed', detail: 'threw' }));
+                if (promo.ok) {
+                    this.snapshot = {
+                        products,
+                        loadedAt: new Date(),
+                        discounts: activeDiscounts(promo.discounts),
+                    };
+                    if (promo.discounts.length)
+                        this.log(`${promo.discounts.length} automatic discount(s)`);
+                }
+                else {
+                    this.snapshot = {
+                        products,
+                        loadedAt: new Date(),
+                        discounts: [],
+                        discountsBlocked: promo.reason === 'unauthorized'
+                            ? 'read_discounts not granted — the merchant must reinstall the app for promotions to show'
+                            : promo.detail,
+                    };
+                    this.log(`discounts unavailable: ${promo.reason}`);
+                }
+                // A fresh catalogue can mean changed prices or stock; do not answer from
+                // variants read against the previous one.
+                this.variants.clear();
+                this.log(`loaded ${products.length} products`);
+            }
+            catch (err) {
+                this.snapshot = {
+                    ...this.snapshot,
+                    lastError: err instanceof Error ? err.message : String(err),
+                };
+                this.log(`refresh FAILED: ${this.snapshot.lastError}`);
+            }
+            finally {
+                this.inFlight = null;
+            }
+        })();
+        return this.inFlight;
+    }
+    /** Every variant of one product, paginated to completion, cached briefly. */
+    async variantsFor(handle, now = Date.now()) {
+        const hit = this.variants.get(handle);
+        if (hit && now - hit.at < VARIANT_TTL_MS)
+            return hit.rows;
+        // Over the global ceiling: serve a stale copy if we have one, and otherwise
+        // say nothing rather than spend more of the merchant's quota. An empty list
+        // reads downstream as "we cannot resolve that combination", which asks the
+        // buyer to choose again — not ideal, and much better than taking the
+        // merchant's own store down with us.
+        if (!this.upstream.take('variants', now)) {
+            this.log('variant fetch ceiling reached — serving stale/empty');
+            return hit?.rows ?? [];
+        }
+        const config = await this.resolveConfig();
+        if (!config)
+            return [];
+        const rows = await fetchProductVariants(config, handle, fetch, (m) => this.log(m));
+        this.variants.set(handle, { at: now, rows });
+        if (this.variants.size > VARIANT_CACHE_MAX) {
+            const oldest = [...this.variants.entries()]
+                .sort((a, b) => a[1].at - b[1].at)
+                .slice(0, Math.floor(VARIANT_CACHE_MAX / 2));
+            for (const [k] of oldest)
+                this.variants.delete(k);
+        }
+        return rows;
+    }
+    timer = null;
+    /** Refresh now, then on an interval. Never throws — boot must not depend on Shopify. */
+    start(intervalMs) {
+        void this.refresh();
+        this.stop();
+        this.timer = setInterval(() => void this.refresh(), intervalMs);
+        // Do not hold the process open for a cache refresh.
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    /**
+     * Stop refreshing.
+     *
+     * A single-shop deployment never needs this — the process owns one catalogue
+     * for its whole life. A multi-tenant one does: when a merchant uninstalls,
+     * an unstoppable timer keeps calling THEIR Shopify with a token they revoked,
+     * forever, for a shop that is no longer a customer.
+     */
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

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

package/dist/challenge.d.ts

@@ -0,0 +1,11 @@
+/** `host=token,host=token` → a lookup. Malformed pairs are skipped, not fatal. */
+export declare const parseChallengeTokens: (raw: string | undefined) => Map<string, string>;
+/**
+ * The token to serve on `host`.
+ *
+ * A per-host entry wins. Falling back to the single-value variable for an
+ * unlisted host is deliberate: every existing single-host deployment keeps
+ * working with no config change.
+ */
+export declare const challengeFor: (host: string | undefined, perHost: string | undefined, single: string | undefined) => string | undefined;
+//# sourceMappingURL=challenge.d.ts.map

package/dist/challenge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge.d.ts","sourceRoot":"","sources":["../src/challenge.ts"],"names":[],"mappings":"AAYA,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAYhF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM,MAAM,GAAG,SAAS,EACxB,SAAS,MAAM,GAAG,SAAS,EAC3B,QAAQ,MAAM,GAAG,SAAS,KACzB,MAAM,GAAG,SAC0E,CAAC"}

package/dist/challenge.js

@@ -0,0 +1,36 @@
+// ChatGPT Apps domain verification, per HOSTNAME.
+//
+// The token OpenAI issues is bound to an ORIGIN, and this service answers on
+// more than one: the merchant's new domain and the one the directories still
+// have registered. A single token served on every host means that verifying the
+// second hostname silently breaks the first — it starts returning the other
+// one's token, and the app that was already verified fails its next re-check.
+// "Verification just dropped" points nowhere near the cause.
+//
+// Both hosts have to stay verified while the listings are moved over one at a
+// time, which is the whole shape of a domain migration.
+/** `host=token,host=token` → a lookup. Malformed pairs are skipped, not fatal. */
+export const parseChallengeTokens = (raw) => {
+    const out = new Map();
+    for (const pair of (raw ?? '').split(',')) {
+        // indexOf, not split('='): a token may legitimately contain '='. Only the
+        // FIRST separator divides host from token.
+        const at = pair.indexOf('=');
+        if (at < 1)
+            continue;
+        const host = pair.slice(0, at).trim().toLowerCase();
+        const token = pair.slice(at + 1).trim();
+        if (host && token)
+            out.set(host, token);
+    }
+    return out;
+};
+/**
+ * The token to serve on `host`.
+ *
+ * A per-host entry wins. Falling back to the single-value variable for an
+ * unlisted host is deliberate: every existing single-host deployment keeps
+ * working with no config change.
+ */
+export const challengeFor = (host, perHost, single) => parseChallengeTokens(perHost).get((host ?? '').toLowerCase()) ?? single ?? undefined;
+//# sourceMappingURL=challenge.js.map

package/dist/challenge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge.js","sourceRoot":"","sources":["../src/challenge.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,gFAAgF;AAChF,4EAA4E;AAC5E,8EAA8E;AAC9E,6DAA6D;AAC7D,EAAE;AACF,8EAA8E;AAC9E,wDAAwD;AAExD,kFAAkF;AAClF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,GAAuB,EAAuB,EAAE;IACnF,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1C,0EAA0E;QAC1E,2CAA2C;QAC3C,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,EAAE,GAAG,CAAC;YAAE,SAAS;QACrB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACxC,IAAI,IAAI,IAAI,KAAK;YAAE,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,IAAwB,EACxB,OAA2B,EAC3B,MAA0B,EACN,EAAE,CACtB,oBAAoB,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,MAAM,IAAI,SAAS,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,141 @@
+/**
+ * One storefront's identity, vocabulary and shop wiring.
+ *
+ * The single-tenant connector this grew out of held all of it as literals:
+ * 'Moody Lenses', 'https://moodycosmetics.com', `list_moody_lenses`. That reads
+ * fine until there is a second merchant, at which point the only way to add one
+ * is to copy 2,443 lines and rename 172 strings — and then fix every bug twice.
+ *
+ * What is NOT here is as deliberate as what is. The product model stays generic
+ * Shopify: no per-merchant fields, no category enums. The moment a merchant
+ * needs a bespoke field, it belongs in their Shopify metafields, not in this
+ * type.
+ */
+/** Secrets never appear in a config file — they arrive through the environment. */
+export type StorefrontSecrets = {
+    clientId: string;
+    clientSecret: string;
+};
+export type StorefrontConfig = {
+    /**
+     * Deployment id, and the path segment it is served under:
+     * shopify.curless.ai/<id>. Also the default token filename.
+     */
+    id: string;
+    /** MCP `serverInfo`, passed through to the host verbatim. */
+    server: {
+        name: string;
+        title: string;
+        /**
+         * The merchant's own site. Left unset it is filled from the shop's
+         * `primaryDomain` — the store knows its own address, and asking a human to
+         * retype it is a chance to get it wrong.
+         */
+        websiteUrl?: string;
+        iconUrl?: string;
+        /**
+         * The merchant's own artwork, as files beside the config.
+         *
+         * Files rather than bytes compiled into the package: one build carrying
+         * every merchant's brand means adding a customer edits shared code, and it
+         * once meant a shop that had supplied no logo served the FIRST merchant's —
+         * naming the wrong party on someone else's connector. Absent here, the
+         * routes 404 and `serverInfo.icons` is omitted; nothing is guessed.
+         *
+         * Paths are resolved against the config file's own directory.
+         */
+        iconFile?: string;
+        logoFile?: string;
+    };
+    /**
+     * How the tools are named.
+     *
+     * A branded deployment sets these and gets `list_moody_lenses`; a model
+     * choosing among several storefront connectors picks by name, and a specific
+     * one is harder to pick wrong. The listed public app leaves them unset and
+     * gets `list_products`, because a review-time capability list has to be fixed
+     * and one install serves exactly one shop.
+     */
+    naming?: {
+        prefix?: string;
+        noun?: string;
+        nounPlural?: string;
+    };
+    shopify: {
+        /**
+         * `env` — one shop, wired at deploy time, credentials from the environment.
+         * `oauth-install` — the listed app: the shop is whoever installed it, so it
+         * cannot be known here. Not implemented yet; declared so the config shape
+         * does not have to change when it is.
+         */
+        mode: 'env' | 'oauth-install';
+        shopDomain?: string;
+        scopes?: string;
+        tokenPath?: string;
+    };
+    /** Where this deployment answers. `publicUrl` differs when the merchant fronts it with their own hostname. */
+    urls: {
+        appUrl: string;
+        publicUrl?: string;
+    };
+    /**
+     * Merchant-specific guidance, appended verbatim to the tool it belongs to.
+     *
+     * Split by tool because it is not all the same kind of fact. At Moody the
+     * colour IS the product name (browse), a pair has one option per eye
+     * (product), and a checkout needs both eyes with the exact shape
+     * {"Left":"-2.00","Right":"-1.50"} (checkout). Generic copy can carry the
+     * RULE — fill every option, never round — but not the shape, and the shape
+     * is what stops an assistant guessing at the moment money is committed.
+     */
+    hints?: {
+        browse?: string;
+        product?: string;
+        checkout?: string;
+        /** One real product name, shown in the `product` argument's description. */
+        example?: string;
+    };
+    legal: {
+        operator?: string;
+        operatorContact?: string;
+        /** Left unset it is filled from the shop's `contactEmail`. */
+        merchantContact?: string;
+        region?: string;
+        updated?: string;
+    };
+};
+/** The words the descriptions speak in, so shared copy can name the merchant's goods. */
+export type Vocabulary = {
+    merchant: string;
+    noun: string;
+    nounPlural: string;
+    hints: {
+        browse: string;
+        product: string;
+        checkout: string;
+        example: string;
+    };
+};
+export declare const vocabulary: (config: StorefrontConfig) => Vocabulary;
+/** What the tools are actually called, once naming has been applied. */
+export type ToolNames = {
+    list: string;
+    get: string;
+    checkout: string;
+    lookupOrder: string;
+};
+export declare const toolNames: (config: StorefrontConfig) => ToolNames;
+/** Everything the runtime needs, with defaults applied once, at the edge. */
+export type ResolvedStorefront = {
+    config: StorefrontConfig;
+    tools: ToolNames;
+    vocab: Vocabulary;
+    appUrl: string;
+    publicUrl: string;
+    redirectUri: string;
+    scopes: string;
+    tokenPath: string;
+    cardUriPrefix: string;
+};
+export declare const resolveStorefront: (config: StorefrontConfig) => ResolvedStorefront;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

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