import type { Pool, PoolClient } from 'pg'; /** * References from a theme's content to data the STORE owns * (`theme.json` widget settings). * * A widget that shows a collection or a product has to name one, and a theme * cannot know the uuids of a store it has never seen. Naming them by uuid (what * the page builder writes) makes the manifest unportable: the uuid belongs to * the author's store and matches nothing anywhere else. So a manifest names * them by BUSINESS KEY, through a token: * * "collection": "store-ref:collection/code/autumn-menu" * "productUuid": "store-ref:product/sku/CAKE-SIG-01" * * `theme:active` looks each one up in the store and substitutes the value that * widget's setting expects — the collection's `code`, the product's `uuid`. * * It never creates anything. Activation installs a theme's content, not a * store's catalogue (The Nguyen, 2026-09-14): a reference that matches nothing * resolves to an empty setting, so the widget renders its own empty state, and * the CLI reports it so the merchant knows which widgets to fill in. */ export declare const STORE_REF_PREFIX = "store-ref:"; export type StoreRefEntity = 'collection' | 'product'; export interface StoreRef { /** The whole token, e.g. `store-ref:product/sku/CAKE-01`. */ token: string; entity: StoreRefEntity; /** The column the key looks up: `code` for a collection, `sku` for a product. */ by: 'code' | 'sku'; key: string; } /** How a reference was satisfied. `name` means the key matched an entity's name, not its key. */ export type StoreRefMatch = 'exact' | 'name' | 'unresolved'; export interface ResolvedStoreRef extends StoreRef { match: StoreRefMatch; /** The value written into the setting: a collection `code`, a product `uuid`, or '' when unresolved. */ value: string; } /** * What each entity contributes to a setting. A widget names a collection by its * code and a product by its uuid, so resolution emits exactly that — no extra * syntax in the token for the caller to get wrong. */ declare const EMITS: Record; export declare function storeRefToken(entity: StoreRefEntity, by: 'code' | 'sku', key: string): string; /** Every store reference appearing anywhere in a value tree, de-duplicated by token. */ export declare function collectStoreRefs(value: unknown): StoreRef[]; /** A token pointing at an entity/key combination this version cannot resolve. */ export declare function isUnsupportedStoreRef(text: string): boolean; /** Look every reference up in the store. Read-only: nothing is created. */ export declare function resolveStoreRefs(conn: Pool | PoolClient, refs: StoreRef[]): Promise; /** * Replace every token with its resolved value, deeply, returning a new value. * An unresolved reference becomes an EMPTY setting rather than a dead key: the * widget then renders the same empty state it shows before a merchant has * picked anything, instead of querying for something that does not exist. */ export declare function applyStoreRefs(value: T, resolved: ResolvedStoreRef[]): T; export { EMITS as STORE_REF_EMITS };