@fayz-ai/shop 0.9.0 → 0.11.0

package/dist/types.d.ts

@@ -1,4 +1,13 @@
 export type ProductStatus = 'draft' | 'active' | 'archived';
+/**
+ * A handling requirement declared on a product (0048).
+ *
+ * This is a DECLARATION, not a guarantee: it is what travels to whoever carries
+ * the parcel — a carrier's refrigerated service, a motoboy, or the merchant's
+ * own car. What RESTRICTS who may carry it is the product's shipping profile
+ * (0049), not this list — this one only travels.
+ */
+export type HandlingRequirement = 'refrigerated' | 'frozen' | 'fragile';
 export interface Product {
     id: string;
     tenantId: string;
@@ -16,11 +25,133 @@ export interface Product {
     images: ProductImage[];
     categoryId: string | null;
     categoryName: string | null;
+    /** False keeps the product out of the freight calculation entirely (0001,
+     *  finally read in FAY-1407). */
     isPhysical: boolean;
     weight: number | null;
+    /** The unit `weight` is in. Honoured by the packing code — it is not
+     *  decoration, and a catalogue in grams quoted as kg is a thousandfold error. */
     weightUnit: string;
+    /** Centimetres (0044b/0046). Null is "not measured", which degrades the cart
+     *  to the store's default package rather than inventing a size. */
+    heightCm?: number | null;
+    widthCm?: number | null;
+    lengthCm?: number | null;
+    /**
+     * Em que embalagem da loja este produto vai (0047). NULL = a padrão da
+     * loja, que é o estado de todo produto no dia da aplicação. Aponta para
+     * plg_shop_packages; a medida está lá, não aqui.
+     */
+    packageId?: string | null;
+    /**
+     * What the box needs from whoever carries it (0048). Empty is "nothing
+     * declared", which is how every catalogue starts.
+     *
+     * On the PRODUCT and not the variant on purpose: needing cold is a property of
+     * what is inside, and a chocolate melts in all three sizes. Weight and
+     * dimensions live on the variant because those genuinely differ.
+     *
+     * Optional and not `HandlingRequirement[]`: eleven apps build Product literals
+     * from source, and a required field on a shared interface makes a declaration
+     * nobody asked for into a build break in every one of them. The live provider
+     * always returns an array, so a reader may treat `undefined` as empty.
+     */
+    handling?: HandlingRequirement[];
+    /** Which delivery profile ships this product (0049). Undefined = the general
+     *  one, which is every product nobody has moved. */
+    shippingProfileId?: string | null;
     createdAt: string;
     updatedAt: string;
+    /**
+     * Option axes from the variant tables (0028), position-ordered — present
+     * when the read path fetched them (products.bySlug attaches them via
+     * ShopProvider.getProductVariants). Undefined means "not fetched", NOT
+     * "no options": list reads skip variants on purpose.
+     */
+    options?: ProductOption[];
+    /** Sellable variants (0028), present under the same conditions as `options`. */
+    variants?: ProductVariant[];
+}
+/**
+ * One option axis of a product ('Tamanho' → ['P','M','G']). Mirrors
+ * plg_shop_product_options: the axis `name` is also the key used inside each
+ * variant's `options` object — that is what ties the two together.
+ */
+export interface ProductOption {
+    id: string;
+    name: string;
+    /** Ordered values for the picker (P before M before G is not alphabetical). */
+    values: string[];
+    position: number;
+}
+/**
+ * The sellable unit once a product has option axes. Mirrors
+ * plg_shop_product_variants: `price` null inherits the product price;
+ * inventory is per-variant (two sizes never share a counter again).
+ */
+export interface ProductVariant {
+    id: string;
+    productId: string;
+    /** The combination this variant IS, e.g. {"Tamanho":"P","Cor":"Azul"}. */
+    options: Record<string, string>;
+    sku: string | null;
+    /** Null inherits the product's price. */
+    price: number | null;
+    compareAtPrice: number | null;
+    inventoryCount: number;
+    position: number;
+    status: 'active' | 'archived';
+    /** Variant-specific photo; null falls back to the product's primary image. */
+    imageId: string | null;
+    /**
+     * 0037's placeholder sellable unit for a product that declares no axes. MUST
+     * BE INVISIBLE to the merchant — no row in the variant grid, no options label.
+     */
+    isDefaultVariant?: boolean;
+    /**
+     * Shipping measurements (0046). Null inherits the product's, exactly like
+     * `price` — a camiseta P and a GG do not occupy the same box, and a
+     * catalogue where every size weighs the same is measured once, on the
+     * product, and never again.
+     */
+    weight?: number | null;
+    weightUnit?: string | null;
+    heightCm?: number | null;
+    widthCm?: number | null;
+    lengthCm?: number | null;
+}
+/** What ShopProvider.getProductVariants answers for one product. */
+export interface ProductVariantSet {
+    options: ProductOption[];
+    variants: ProductVariant[];
+}
+/** One axis as the admin submits it. Order of `values` is the picker's order. */
+export interface ProductOptionInput {
+    name: string;
+    values: string[];
+}
+/**
+ * The variant fields the admin owns. `inventoryCount` is deliberately ABSENT:
+ * since 0034 stock is a ledger and since 0036 `inventory_count` is its mirror,
+ * so a write here would be a second truth. Stock moves through
+ * ShopProvider.setVariantStock, which appends a movement.
+ */
+export interface UpdateProductVariantInput {
+    sku?: string | null;
+    price?: number | null;
+    compareAtPrice?: number | null;
+    position?: number;
+    status?: 'active' | 'archived';
+    imageId?: string | null;
+    weight?: number | null;
+    weightUnit?: string | null;
+    heightCm?: number | null;
+    widthCm?: number | null;
+    lengthCm?: number | null;
+}
+export interface CreateProductVariantInput extends UpdateProductVariantInput {
+    /** The combination this variant IS. Empty is refused — that shape is 0037's. */
+    options: Record<string, string>;
 }
 export interface ProductImage {
     id: string;
@@ -47,6 +178,12 @@ export interface CreateProductInput {
     isPhysical?: boolean;
     weight?: number;
     weightUnit?: string;
+    heightCm?: number | null;
+    widthCm?: number | null;
+    lengthCm?: number | null;
+    packageId?: string | null;
+    handling?: HandlingRequirement[];
+    shippingProfileId?: string | null;
 }
 export interface UpdateProductInput {
     name?: string;
@@ -64,6 +201,12 @@ export interface UpdateProductInput {
     isPhysical?: boolean;
     weight?: number | null;
     weightUnit?: string;
+    heightCm?: number | null;
+    widthCm?: number | null;
+    lengthCm?: number | null;
+    packageId?: string | null;
+    handling?: HandlingRequirement[];
+    shippingProfileId?: string | null;
 }
 export interface ListProductsOptions {
     status?: ProductStatus;
@@ -167,9 +310,25 @@ export interface Order {
     paymentMethodKind: PaymentMethodKind | null;
     paidAt: string | null;
     items: OrderItem[];
+    /**
+     * What the buyer needs to follow the box (0052). Only `getOrder` fills it —
+     * on a list, `[]` means "not asked for" as much as "nothing shipped".
+     */
+    shipments?: OrderShipment[];
     createdAt: string;
     updatedAt: string;
 }
+/** One non-cancelled shipment, as the buyer's own window returns it. */
+export interface OrderShipment {
+    id: string;
+    status: string;
+    carrier: string | null;
+    trackingCode: string | null;
+    trackingUrl: string | null;
+    shippedAt: string | null;
+    estimatedDeliveryAt: string | null;
+    deliveredAt: string | null;
+}
 export interface OrderItem {
     id: string;
     orderId: string;
@@ -223,6 +382,13 @@ export interface ListOrdersOptions {
 export interface PlaceOrderLine {
     productId: string;
     quantity: number;
+    /**
+     * Variant to sell (0028/0029). When present the server prices the line from
+     * the variant, checks and decrements the VARIANT's stock, and derives the
+     * options label from the variant's combination. Absent = the product-level
+     * path, unchanged.
+     */
+    variantId?: string;
     /** Variant/options label appended to the stored item name (display only). */
     optionsLabel?: string;
 }
@@ -245,8 +411,125 @@ export interface ShippingAddressInput {
     recipient?: string;
     phone?: string;
     label?: string;
+    /**
+     * CPF/CNPJ of whoever is buying — digits only. It is NOT part of the address:
+     * it travels here because shop_place_order cannot grow a parameter without a
+     * DROP, and 0050's BEFORE INSERT trigger lifts it into
+     * plg_shop_orders.customer_document and removes it from the stored jsonb.
+     * Read the column, never this field.
+     */
+    document?: string;
 }
 export type PaymentMethodKind = 'pix' | 'credit_card' | 'debit_card' | 'boleto' | 'cash' | 'other';
+export interface CreateFulfillmentInput {
+    orderId: string;
+    /** Free text: the merchant's own courier is as valid as a named carrier. */
+    carrier?: string;
+    /** With one, the shipment is already in transit; without, it is picking. */
+    trackingCode?: string;
+    locationId?: string;
+    notes?: string;
+    /** Partial shipment. Omitted means everything still outstanding. */
+    items?: Array<{
+        orderItemId: string;
+        quantity: number;
+    }>;
+}
+export interface ShipFulfillmentInput {
+    trackingCode?: string;
+    trackingUrl?: string;
+    carrier?: string;
+}
+/**
+ * O carrinho congelado enquanto o comprador paga.
+ *
+ * Existe porque o pedido passou a nascer DEPOIS do pagamento. Entre "escolhi
+ * pagar" e "paguei" não há pedido nenhum — há esta sessão, com os preços que o
+ * SERVIDOR recalculou, e é dela que o pedido é criado quando o dinheiro entra.
+ */
+export interface CheckoutSessionInput {
+    items: Array<{
+        productId: string;
+        variantId?: string | null;
+        quantity: number;
+        optionsLabel?: string | null;
+    }>;
+    customer: {
+        name?: string | null;
+        email: string;
+    };
+    shippingAddress?: ShippingAddressInput;
+    discountCode?: string | null;
+    paymentMethod?: PaymentMethodKind;
+}
+export interface CheckoutSession {
+    sessionId: string;
+    /** Recalculado no servidor. O navegador exibe; nunca decide. */
+    total: number;
+    charge: PaymentCharge | null;
+    state: 'open' | 'paid' | 'failed' | 'expired';
+}
+/** `orderId` só aparece quando o pagamento entrou — é ele que prova a compra. */
+export interface CheckoutSettlement {
+    /** `pending` is what the acquirer answers while the buyer still has the QR
+     *  code open — the ordinary case, and the one a caller must never read as a
+     *  refusal. Only `failed`, `expired` and `cancelled` end the wait. */
+    state: 'open' | 'pending' | 'paid' | 'failed' | 'expired' | 'cancelled' | 'unknown';
+    orderId?: string | null;
+    reason?: string | null;
+}
+/** A carrier label, from quote to tracking. `labelUrl` is a PDF the merchant prints. */
+export interface ShippingLabelOption {
+    serviceId: number;
+    name: string;
+    carrier: string;
+    price: number;
+    etaMinDays?: number | null;
+    etaMaxDays?: number | null;
+}
+/** A carrier drop-off point, as a settings screen lists it. */
+export interface ShippingAgency {
+    id: string;
+    name: string;
+    city: string;
+    state: string;
+    address: string;
+    /** Carrier service ids this one accepts — a choice that hides them is a
+     *  choice the merchant discovers is wrong at the first dispatch. */
+    services: string[];
+}
+export interface ShippingLabel {
+    labelId: string;
+    labelUrl?: string | null;
+    status?: string | null;
+    tracking?: {
+        code: string | null;
+        status: string | null;
+        url: string | null;
+    } | null;
+}
+/** What a connected acquirer can be asked to open. Card waits for hosted fields. */
+export type PaymentChargeMethod = 'pix';
+/**
+ * A charge the buyer can act on. `qrcodeBase64` is a bare base64 PNG — no
+ * `data:` prefix — because that is how the provider returns it.
+ */
+export interface PaymentCharge {
+    emv: string;
+    qrcodeBase64: string | null;
+    expiresAt: string;
+}
+/**
+ * `unopened` is not an error: the page may ask for the state before the charge
+ * call has returned. `failed` is the provider's final no.
+ */
+export interface PaymentChargeResult {
+    state: 'pending' | 'paid' | 'refunded' | 'failed' | 'unopened';
+    orderId: string;
+    reference?: string | null;
+    charge?: PaymentCharge | null;
+    providerStatus?: string | null;
+}
 /**
  * A range of postal codes the store delivers to, with its own price and ETA.
  *
@@ -268,9 +551,208 @@ export interface ShippingZone {
     etaMaxDays?: number | null;
     active: boolean;
     sortOrder: number;
+    /**
+     * A zone the store REFUSES (0048) — "não entrego aqui", by any means.
+     *
+     * It beats every other zone covering the same postcode and it beats a carrier
+     * quote, because the refusal is about the store and not about who carries the
+     * parcel. Enforced server-side on the order, so a direct POST cannot get
+     * around it. `rate` and the ETA are ignored on an excluded zone.
+     *
+     * Not-cadastrar is a different thing: a broad zone covering a whole region
+     * already accepts the street the merchant wants to avoid, and there was no way
+     * to carve an exception out of it.
+     */
+    excluded: boolean;
+    /** Which profile owns this range (0049). Undefined = the general profile. */
+    profileId?: string | null;
 }
 export type CreateShippingZoneInput = Omit<ShippingZone, 'id' | 'tenantId'>;
 export type UpdateShippingZoneInput = Partial<CreateShippingZoneInput>;
+export type ShippingPackageKind = 'box' | 'envelope' | 'soft';
+/**
+ * A box the store actually owns (plg_shop_packages, 0046).
+ *
+ * The freight engine picks the SMALLEST of these the cart fits in and adds
+ * `emptyWeightGrams` to what the carrier weighs. Before this cadastro existed
+ * the box was a constant in the edge function — 4×16×20cm for every store —
+ * and the difference between the quote and the label came out of the
+ * merchant's margin.
+ *
+ * `isDefault` is the box a cart falls back to when some item has no
+ * measurements. That fallback used to be the constant; it is data now.
+ */
+export interface ShippingPackage {
+    id: string;
+    tenantId: string;
+    name: string;
+    kind: ShippingPackageKind;
+    heightCm: number;
+    widthCm: number;
+    lengthCm: number;
+    /** Grams, because that is how a merchant reads a carton's own weight. */
+    emptyWeightGrams: number;
+    isDefault: boolean;
+    active: boolean;
+}
+export type CreateShippingPackageInput = Omit<ShippingPackage, 'id' | 'tenantId'>;
+export type UpdateShippingPackageInput = Partial<CreateShippingPackageInput>;
+/**
+ * A named group of products with its own delivery zones (0049).
+ *
+ * The general mechanism behind "estes produtos vão de outro jeito", copied from
+ * Shopify's shipping profiles: refrigerated, fragile, oversized and made-to-order
+ * are all the same shape — a set of products the store ships differently — and
+ * modelling them one column at a time is how a settings screen ends up with four
+ * radios that each answer one merchant's question.
+ *
+ * INHERITANCE is by NULL on both ends: a product with no profile uses the
+ * general one, and a zone with no profile belongs to the general one. That is
+ * what lets this ship without migrating a single existing product or zone.
+ */
+export interface ShippingProfile {
+    id: string;
+    tenantId: string;
+    name: string;
+    /**
+     * Whether a freight gateway may quote for the products in this profile.
+     *
+     * Undefined inherits `StoreSettings.carrierQuotes`. `false` is what replaces
+     * the old cold-chain policy: these products leave only through the zones the
+     * store declared itself. In a cart that mixes profiles the most restrictive one
+     * wins — otherwise "these do not go by truck" would be undone by adding a mug.
+     */
+    carrierQuotes?: boolean;
+    /** The general profile, so the screen has somewhere to hang unprofiled zones. */
+    isDefault: boolean;
+}
+export type CreateShippingProfileInput = Omit<ShippingProfile, 'id' | 'tenantId'>;
+export type UpdateShippingProfileInput = Partial<CreateShippingProfileInput>;
+/**
+ * The store-wide delivery fallback (public.shipping_settings, 0015).
+ *
+ * A zone always wins over this. It is what a store charges for an address no
+ * zone covers — and for a store that has declared no zone at all, which is how
+ * most start. A tenant with no row at all charges nothing, which is the safe
+ * default: inventing a freight nobody configured is worse than free delivery.
+ */
+export interface ShippingSettings {
+    flatRate: number;
+    /** Subtotal (after discount) at or above which delivery is free. */
+    freeAbove?: number | null;
+    currency: string;
+}
+export type UpdateShippingSettingsInput = Partial<ShippingSettings>;
+/**
+ * Per-field checkout policy. Keyed by the form field the storefront renders.
+ *
+ * A record rather than columns because the SET OF FIELDS is the variable part:
+ * a store selling downloads has no use for a district, and the next storefront
+ * will want one nobody has thought of. `visible: false` implies not required —
+ * a field nobody can see cannot be filled in.
+ */
+export type CheckoutFieldKey = 'name' | 'email' | 'phone' | 'document' | 'street' | 'number' | 'complement' | 'district' | 'city' | 'state' | 'postalCode';
+export interface CheckoutFieldPolicy {
+    visible?: boolean;
+    required?: boolean;
+}
+/**
+ * The store's commercial policy — what plg_shop_settings holds (0044b).
+ *
+ * Every field is OPTIONAL and `undefined` means NOT DECIDED, which is a
+ * different thing from a false or an empty list: not-decided keeps whatever the
+ * app declared in its StorefrontConfig, while `paymentMethods: []` would be a
+ * merchant who accepts nothing. That distinction is what lets this ship to eight
+ * live storefronts without changing any of them on deploy day.
+ *
+ * Two of these are enforced SERVER-SIDE by a trigger (`paymentMethods`,
+ * `guestCheckout`); the rest are read by the storefront. The docs on each say
+ * which, because "the checkbox is off" and "the server refuses" are promises of
+ * very different strength.
+ */
+export interface StoreSettings {
+    /** Vitrine display. Undefined = the app's own currency/locale. */
+    currency?: string;
+    locale?: string;
+    showOutOfStock?: boolean;
+    /** Admin-side: makes SKU mandatory on the product form. Not a storefront rule. */
+    requireSku?: boolean;
+    /** ERP ownership of stock (0029). 'external' means a connector owns the numbers. */
+    stockOwnership?: 'internal' | 'external';
+    /** What the checkout may offer. ENFORCED: an order naming a method outside
+     *  this list is refused by the server, not merely hidden by the form. */
+    paymentMethods?: PaymentMethodKind[];
+    /** Which connected gateway charges, when more than one is connected. The id of
+     *  a ConnectorDefinition ('appmax'), never a credential. */
+    paymentProvider?: string;
+    /** ENFORCED: a storefront order with no account-linked customer is refused
+     *  when this is explicitly false. */
+    guestCheckout?: boolean;
+    /** Storefront-side only — confirming an e-mail is a fact about the auth
+     *  provider, not about the order, so the server does not police it. */
+    requireConfirmedEmail?: boolean;
+    marketingOptIn?: boolean;
+    discountsEnabled?: boolean;
+    checkoutFields?: Partial<Record<CheckoutFieldKey, CheckoutFieldPolicy>>;
+    /** 'never' — every shipment is created by hand. 'on_payment' — one is created
+     *  when the payment is confirmed. 'always' — when the order is placed. */
+    autoFulfill?: 'never' | 'on_payment' | 'always';
+    notifyNewOrder?: boolean;
+    notifyLowStock?: boolean;
+    /**
+     * A declaração que viaja com o pedido — para você, para o motoboy, e na
+     * observação da etiqueta. Nunca mostrada ao comprador.
+     *
+     * Onde ficou a política de frio: num PERFIL DE ENTREGA (0049). "Refrigerado só
+     * sai no meu carro" é uma frase sobre logística, e uma coluna de três valores
+     * só respondia por temperatura — a loja seguinte pede o mesmo para frágil, para
+     * volumoso, para sob encomenda. Um perfil atende os quatro sem código novo.
+     */
+    /**
+     * Whether a freight GATEWAY may quote for this store (0048).
+     *
+     * Melhor Envio is not a carrier — it is a gateway that brings Correios,
+     * Jadlog, Loggi and others behind one connection. So the store's question is
+     * not "which carrier" but WHO CALCULATES: the merchant, from her zones, or a
+     * gateway, from the shopper's postcode.
+     *
+     * `false` = the merchant calculates, and no gateway is asked even if one is
+     * connected. Undefined = not decided, which behaves as today (ask if
+     * connected). It has to be storable rather than inferred from "no connection":
+     * the day someone connects a gateway in this app, a store that dispatches by
+     * hand would start receiving carrier prices it never chose — and 0044b makes a
+     * gateway quote WIN over the zones when it answers.
+     */
+    carrierQuotes?: boolean;
+    /**
+     * The note that travels with the parcel ("caixa térmica com gelo, entregar em
+     * até 24h"). Admin-side and carrier-side only — never shown to the shopper,
+     * which is why `shop_store_settings()` does not return it.
+     */
+    handlingNote?: string;
+}
+export type UpdateStoreSettingsInput = Partial<StoreSettings>;
+/**
+ * The answer to "does this store deliver to this postcode?" (0048,
+ * `shop_delivery_check`), asked with the address and BEFORE the card.
+ *
+ * Two separate facts, because they are not the same question:
+ *   · `refused` — an exclusion zone covers it. A no from the store, true even
+ *     where a carrier would happily deliver.
+ *   · `ownZone` — a zone of the store's own covers it. What tells "our car"
+ *     from "a gateway", and what a shipping profile with the gateway off (0049)
+ *     narrows a product to.
+ *
+ * Deliberately NOT "is there freight": that is `quoteShipping`, which also
+ * consults a carrier. Answering both here would tell every carrier-only store
+ * that it does not deliver anywhere.
+ */
+export interface DeliveryCheck {
+    refused: boolean;
+    /** The exclusion zone's name, so the shopper reads a reason and not an error. */
+    refusedZone?: string | null;
+    ownZone: boolean;
+}
 /**
  * One delivery option for a postal code, as quoted by shop_quote_shipping.
  *
@@ -345,6 +827,12 @@ export interface PlaceOrderInput {
     shippingAddress?: ShippingAddressInput;
     /** How the buyer is paying. Opens the ledger row in public.transactions. */
     paymentMethod?: PaymentMethodKind;
+    /**
+     * Machine-readable metadata stamped on the order, namespaced by contributor
+     * (spine M7's order.metadata extension point). Persisted by providers that
+     * support it (0029's plg_shop_orders.metadata); others may ignore it.
+     */
+    metadata?: Record<string, unknown>;
     items: PlaceOrderLine[];
 }
 export interface ShopCustomer {
@@ -354,6 +842,10 @@ export interface ShopCustomer {
     lastName: string;
     email: string | null;
     phone: string | null;
+    /** CPF/CNPJ, digits only. The person's, not the order's — an invoice issued
+     *  months later needs the document that was valid on the day it is issued,
+     *  and the order keeps its own frozen copy for that. */
+    document?: string | null;
     notes: string | null;
     ordersCount: number;
     totalSpent: number;
@@ -365,6 +857,7 @@ export interface CreateCustomerInput {
     lastName?: string;
     email?: string;
     phone?: string;
+    document?: string;
     notes?: string;
 }
 export interface UpdateCustomerInput {
@@ -372,6 +865,7 @@ export interface UpdateCustomerInput {
     lastName?: string;
     email?: string | null;
     phone?: string | null;
+    document?: string | null;
     notes?: string | null;
 }
 export interface ListCustomersOptions {
@@ -530,4 +1024,198 @@ export interface CartTotals {
     shippingTotal: number;
     total: number;
 }
+export type EmailEventKey = 'order_confirmation' | 'order_paid' | 'order_shipped' | 'order_delivered' | 'order_cancelled' | 'refund_confirmation' | 'customer_welcome' | 'abandoned_cart';
+/** Transacional responde a um ato do cliente; marketing é iniciativa da loja —
+ *  e é a distinção que decide se o envio precisa de consentimento. */
+export type EmailTemplateKind = 'transactional' | 'marketing';
+export interface EmailTemplate {
+    id: string;
+    tenantId: string;
+    event: EmailEventKey;
+    /** Ligado. Null = usar o `defaultEnabled` do catálogo — a mesma regra de
+     *  subject/body. Sem isso, salvar só o TEXTO de um modelo nunca tocado
+     *  gravava `false` e desligava o e-mail sem ninguém pedir. */
+    enabled: boolean | null;
+    /** Assunto. Null = usar o padrão que o SDK define para este evento. */
+    subject: string | null;
+    /** Corpo. Null = usar o padrão. */
+    body: string | null;
+    updatedAt: string;
+}
+export interface UpsertEmailTemplateInput {
+    event: EmailEventKey;
+    /** Omitir = não mexer no estado atual. Null = voltar ao padrão do catálogo. */
+    enabled?: boolean | null;
+    subject?: string | null;
+    body?: string | null;
+}
+export interface CustomerGroup {
+    id: string;
+    tenantId: string;
+    name: string;
+    description: string | null;
+    /** Chip colour in the admin. Null = default neutral. */
+    color: string | null;
+    /** Members, cheapest shape — counts and chips without a customer join. */
+    customerIds: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateCustomerGroupInput {
+    name: string;
+    description?: string | null;
+    color?: string | null;
+    customerIds?: string[];
+}
+export type UpdateCustomerGroupInput = Partial<CreateCustomerGroupInput>;
+/**
+ * A segment's rule, as explicit columns rather than opaque JSON: every
+ * criterion here is one the customer list can actually evaluate, so a saved
+ * segment always has a real, checkable membership. A free-form rule blob would
+ * let the admin store conditions nothing knows how to answer.
+ *
+ * All criteria are AND-ed. Every field null = matches everyone.
+ */
+export interface CustomerSegment {
+    id: string;
+    tenantId: string;
+    name: string;
+    description: string | null;
+    minOrders: number | null;
+    maxOrders: number | null;
+    minSpent: number | null;
+    maxSpent: number | null;
+    /** ISO date — customer joined on or after this day. */
+    joinedAfter: string | null;
+    joinedBefore: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateCustomerSegmentInput {
+    name: string;
+    description?: string | null;
+    minOrders?: number | null;
+    maxOrders?: number | null;
+    minSpent?: number | null;
+    maxSpent?: number | null;
+    joinedAfter?: string | null;
+    joinedBefore?: string | null;
+}
+export type UpdateCustomerSegmentInput = Partial<CreateCustomerSegmentInput>;
+export interface Collection {
+    id: string;
+    tenantId: string;
+    title: string;
+    /** URL segment on the storefront. Derived from the title when omitted. */
+    handle: string;
+    description: string | null;
+    imageUrl: string | null;
+    /** Storefront <title>; falls back to `title` when empty. */
+    seoTitle: string | null;
+    seoDescription: string | null;
+    published: boolean;
+    sortOrder: number;
+    /** Members, cheapest possible shape — counts and chips without a product join. */
+    productIds: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateCollectionInput {
+    title: string;
+    handle?: string;
+    description?: string | null;
+    imageUrl?: string | null;
+    seoTitle?: string | null;
+    seoDescription?: string | null;
+    published?: boolean;
+    sortOrder?: number;
+    productIds?: string[];
+}
+export interface UpdateCollectionInput {
+    title?: string;
+    handle?: string;
+    description?: string | null;
+    imageUrl?: string | null;
+    seoTitle?: string | null;
+    seoDescription?: string | null;
+    published?: boolean;
+    sortOrder?: number;
+    productIds?: string[];
+}
+export type GiftCardStatus = 'active' | 'redeemed' | 'expired' | 'disabled';
+export interface GiftCard {
+    id: string;
+    tenantId: string;
+    /** What the buyer types at checkout. Unique per tenant, stored upper-case. */
+    code: string;
+    /** Face value at issue, in the store currency. Never changes. */
+    initialBalance: number;
+    /** What is left to spend. The only field redemption moves. */
+    balance: number;
+    currency: string;
+    status: GiftCardStatus;
+    /** Null = never expires. */
+    expiresAt: string | null;
+    /** Recipient, when the card was issued to a known customer. */
+    customerId: string | null;
+    customerEmail: string | null;
+    note: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateGiftCardInput {
+    code?: string;
+    initialBalance: number;
+    currency?: string;
+    status?: GiftCardStatus;
+    expiresAt?: string | null;
+    customerId?: string | null;
+    customerEmail?: string | null;
+    note?: string | null;
+}
+export interface UpdateGiftCardInput {
+    code?: string;
+    /** Adjusting the remaining balance (a goodwill top-up, a correction). */
+    balance?: number;
+    status?: GiftCardStatus;
+    expiresAt?: string | null;
+    customerId?: string | null;
+    customerEmail?: string | null;
+    note?: string | null;
+}
+export type MediaFileKind = 'image' | 'video' | 'document';
+/**
+ * The record a file hangs off.
+ *
+ * Without this a media library is a wall of anonymous thumbnails: a merchant can
+ * see that a photo is bad and has nowhere to go to replace it. Only products own
+ * files today; the shape is a discriminated union so a collection or a category
+ * can join without changing the screens that read it.
+ */
+export interface MediaFileReference {
+    type: 'product';
+    /** The record's id — what the admin route is built from. */
+    id: string;
+    /** The record's name, for the card's link. */
+    label: string;
+    /** The attachment row (plg_shop_product_images.id). Deleting a file from the
+     *  library targets this: detaching it IS the deletion. */
+    attachmentId: string;
+    /** True for the photo the storefront leads with. */
+    isCover?: boolean;
+}
+export interface MediaFile {
+    /** Storage path relative to the bucket — the stable identity. */
+    id: string;
+    name: string;
+    url: string;
+    kind: MediaFileKind;
+    /** Bytes. 0 when the backend does not report a size. */
+    size: number;
+    /** Upper-cased extension, for the card's type caption (WEBP, MP4…). */
+    extension: string;
+    createdAt: string;
+    /** Absent for files uploaded straight to the library, which belong to nothing. */
+    reference?: MediaFileReference;
+}
 //# sourceMappingURL=types.d.ts.map