@fayz-ai/shop 0.7.0 → 0.8.2

package/src/supabase-provider.ts

@@ -1,6 +1,7 @@
 import { getSupabaseClientOptional } from '@fayz-ai/core'
 import type { ShopProvider } from './provider'
 import { getShopTenantId } from './tenant'
+import { T } from './tables'
 import type {
   Product, ProductImage, Category,
   Order, ShopCustomer, Discount,
@@ -8,8 +9,8 @@ import type {
   CreateCategoryInput, UpdateCategoryInput,
   CreateOrderInput, UpdateOrderInput, ListOrdersOptions, PlaceOrderInput,
   CreateCustomerInput, UpdateCustomerInput, ListCustomersOptions, ResolveCustomerInput,
-  CreateDiscountInput, UpdateDiscountInput, ListDiscountsOptions,
-} from './types'
+  CreateDiscountInput, UpdateDiscountInput, ListDiscountsOptions, OrderItem,
+  ShippingZone, CreateShippingZoneInput, UpdateShippingZoneInput } from './types'
 
 function getDb(): any {
   const supabase = getSupabaseClientOptional()
@@ -30,6 +31,44 @@ function asUuid(value: string | null | undefined): string | null {
     : null
 }
 
+/** 8 bare digits, zero-padded — the shape shipping_zones stores and compares. */
+function toPostalDigits(value: string | undefined | null): string | undefined {
+  const digits = String(value ?? '').replace(/\D/g, '')
+  return digits ? digits.padStart(8, '0').slice(0, 8) : undefined
+}
+
+function rowToShippingZone(row: any): ShippingZone {
+  return {
+    id: row.id,
+    tenantId: row.tenant_id,
+    name: row.name,
+    carrier: row.carrier ?? null,
+    postalFrom: String(row.postal_from ?? '').trim(),
+    postalTo: String(row.postal_to ?? '').trim(),
+    rate: Number(row.rate ?? 0),
+    freeAbove: row.free_above == null ? null : Number(row.free_above),
+    etaMinDays: row.eta_min_days ?? null,
+    etaMaxDays: row.eta_max_days ?? null,
+    active: row.active ?? true,
+    sortOrder: row.sort_order ?? 0,
+  }
+}
+
+function shippingZonePayload(input: Partial<CreateShippingZoneInput>): Record<string, unknown> {
+  const payload: Record<string, unknown> = {}
+  if (input.name !== undefined) payload.name = input.name
+  if (input.carrier !== undefined) payload.carrier = input.carrier || null
+  if (input.postalFrom !== undefined) payload.postal_from = toPostalDigits(input.postalFrom)
+  if (input.postalTo !== undefined) payload.postal_to = toPostalDigits(input.postalTo)
+  if (input.rate !== undefined) payload.rate = input.rate
+  if (input.freeAbove !== undefined) payload.free_above = input.freeAbove ?? null
+  if (input.etaMinDays !== undefined) payload.eta_min_days = input.etaMinDays ?? null
+  if (input.etaMaxDays !== undefined) payload.eta_max_days = input.etaMaxDays ?? null
+  if (input.active !== undefined) payload.active = input.active
+  if (input.sortOrder !== undefined) payload.sort_order = input.sortOrder
+  return payload
+}
+
 function rowToProduct(row: any): Product {
   return {
     id: row.id,
@@ -81,6 +120,26 @@ function rowToCategory(row: any): Category {
   }
 }
 
+/**
+ * Order items were being passed through raw, so every snake_case column arrived
+ * undefined on the camelCase type: unit_price, image_url and product_id were all
+ * lost. `total` survived only because the name matches in both, which is exactly
+ * why the bug looked like "price is zero" instead of "nothing is mapped".
+ */
+function rowToOrderItem(row: any): OrderItem {
+  return {
+    id: row.id,
+    orderId: row.order_id,
+    productId: row.product_id ?? null,
+    name: row.name,
+    sku: row.sku ?? null,
+    quantity: row.quantity ?? 0,
+    unitPrice: row.unit_price ?? 0,
+    total: row.total ?? 0,
+    imageUrl: row.image_url ?? null,
+  }
+}
+
 function rowToOrder(row: any): Order {
   return {
     id: row.id,
@@ -100,7 +159,10 @@ function rowToOrder(row: any): Order {
     customerEmail: row.customer_email,
     discountCode: row.discount_code,
     notes: row.notes,
-    items: Array.isArray(row.items) ? row.items : [],
+    shippingAddress: row.shipping_address ?? null,
+    paymentMethodKind: row.payment_method_kind ?? null,
+    paidAt: row.paid_at ?? null,
+    items: Array.isArray(row.items) ? row.items.map(rowToOrderItem) : [],
     createdAt: row.created_at,
     updatedAt: row.updated_at,
   }
@@ -150,7 +212,7 @@ export class SupabaseShopProvider implements ShopProvider {
   async listProducts(options?: ListProductsOptions): Promise<Product[]> {
     const db = getDb()
     const tenantId = getTenantId()
-    let q = db.from('shop_products').select('*, images:shop_product_images(*)')
+    let q = db.from(T.products).select(`*, images:${T.productImages}(*)`)
     if (tenantId) q = q.eq('tenant_id', tenantId)
     if (options?.status) q = q.eq('status', options.status)
     if (options?.categoryId) q = q.eq('category_id', options.categoryId)
@@ -167,8 +229,8 @@ export class SupabaseShopProvider implements ShopProvider {
   async getProduct(id: string): Promise<Product | null> {
     const db = getDb()
     const { data, error } = await db
-      .from('shop_products')
-      .select('*, images:shop_product_images(*)')
+      .from(T.products)
+      .select(`*, images:${T.productImages}(*)`)
       .eq('id', id)
       .maybeSingle()
     if (error) throw error
@@ -179,7 +241,7 @@ export class SupabaseShopProvider implements ShopProvider {
     const db = getDb()
     const tenantId = getTenantId()
     const { data, error } = await db
-      .from('shop_products')
+      .from(T.products)
       .insert({
         tenant_id: tenantId,
         name: input.name,
@@ -198,7 +260,7 @@ export class SupabaseShopProvider implements ShopProvider {
         weight: input.weight ?? null,
         weight_unit: input.weightUnit ?? 'kg',
       })
-      .select('*, images:shop_product_images(*)')
+      .select(`*, images:${T.productImages}(*)`)
       .single()
     if (error) throw error
     return rowToProduct(data)
@@ -220,15 +282,15 @@ export class SupabaseShopProvider implements ShopProvider {
     if (input.isPhysical !== undefined) updates.is_physical = input.isPhysical
     if (input.weight !== undefined) updates.weight = input.weight
     const { data, error } = await db
-      .from('shop_products').update(updates).eq('id', id)
-      .select('*, images:shop_product_images(*)')
+      .from(T.products).update(updates).eq('id', id)
+      .select(`*, images:${T.productImages}(*)`)
       .single()
     if (error) throw error
     return rowToProduct(data)
   }
 
   async deleteProduct(id: string): Promise<void> {
-    const { error } = await getDb().from('shop_products').delete().eq('id', id)
+    const { error } = await getDb().from(T.products).delete().eq('id', id)
     if (error) throw error
   }
 
@@ -239,16 +301,63 @@ export class SupabaseShopProvider implements ShopProvider {
     const { error: uploadErr } = await db.storage.from('shop-images').upload(path, file)
     if (uploadErr) throw uploadErr
     const { data: { publicUrl } } = db.storage.from('shop-images').getPublicUrl(path)
+
+    // Every upload used to land as sort_order 0 / is_primary false, so a product
+    // whose only photo was uploaded here had NO primary at all, and a second one
+    // tied with the first for position. New photos now go to the end, and the
+    // first photo a product ever gets becomes its primary.
+    const { data: existing } = await db
+      .from(T.productImages)
+      .select('id,sort_order')
+      .eq('product_id', productId)
+      .order('sort_order', { ascending: false })
+      .limit(1)
+    const first = !existing || existing.length === 0
+    const nextOrder = first ? 0 : (existing[0].sort_order ?? 0) + 1
+
     const { data, error } = await db
-      .from('shop_product_images')
-      .insert({ product_id: productId, tenant_id: tenantId, url: publicUrl, sort_order: 0, is_primary: false })
+      .from(T.productImages)
+      .insert({
+        product_id: productId, tenant_id: tenantId, url: publicUrl,
+        sort_order: nextOrder, is_primary: first,
+      })
       .select().single()
     if (error) throw error
     return rowToImage(data)
   }
 
+  async updateProductImage(
+    imageId: string,
+    input: { isPrimary?: boolean; sortOrder?: number; altText?: string | null },
+  ): Promise<ProductImage> {
+    const db = getDb()
+    const updates: Record<string, unknown> = {}
+    if (input.sortOrder !== undefined) updates.sort_order = input.sortOrder
+    if (input.altText !== undefined) updates.alt_text = input.altText
+    if (input.isPrimary !== undefined) updates.is_primary = input.isPrimary
+
+    // Demote the incumbent first. Doing it after would leave a window with two
+    // primaries, and if the second statement failed the product would keep two
+    // for good.
+    if (input.isPrimary) {
+      const { data: target } = await db
+        .from(T.productImages).select('product_id').eq('id', imageId).single()
+      if (target?.product_id) {
+        await db.from(T.productImages)
+          .update({ is_primary: false })
+          .eq('product_id', target.product_id)
+          .neq('id', imageId)
+      }
+    }
+
+    const { data, error } = await db
+      .from(T.productImages).update(updates).eq('id', imageId).select().single()
+    if (error) throw error
+    return rowToImage(data)
+  }
+
   async deleteProductImage(imageId: string): Promise<void> {
-    const { error } = await getDb().from('shop_product_images').delete().eq('id', imageId)
+    const { error } = await getDb().from(T.productImages).delete().eq('id', imageId)
     if (error) throw error
   }
 
@@ -259,7 +368,7 @@ export class SupabaseShopProvider implements ShopProvider {
   async listCategories(): Promise<Category[]> {
     const db = getDb()
     const tenantId = getTenantId()
-    let q = db.from('shop_categories').select('*').order('sort_order', { ascending: true })
+    let q = db.from(T.categories).select('*').order('sort_order', { ascending: true })
     if (tenantId) q = q.eq('tenant_id', tenantId)
     const { data, error } = await q
     if (error) throw error
@@ -269,7 +378,7 @@ export class SupabaseShopProvider implements ShopProvider {
   async createCategory(input: CreateCategoryInput): Promise<Category> {
     const db = getDb()
     const { data, error } = await db
-      .from('shop_categories')
+      .from(T.categories)
       .insert({ tenant_id: getTenantId(), name: input.name, slug: input.slug ?? slugify(input.name), description: input.description ?? null, parent_id: input.parentId ?? null, sort_order: input.sortOrder ?? 0 })
       .select().single()
     if (error) throw error
@@ -284,13 +393,13 @@ export class SupabaseShopProvider implements ShopProvider {
     if (input.description !== undefined) updates.description = input.description
     if (input.parentId !== undefined) updates.parent_id = input.parentId
     if (input.sortOrder !== undefined) updates.sort_order = input.sortOrder
-    const { data, error } = await db.from('shop_categories').update(updates).eq('id', id).select().single()
+    const { data, error } = await db.from(T.categories).update(updates).eq('id', id).select().single()
     if (error) throw error
     return rowToCategory(data)
   }
 
   async deleteCategory(id: string): Promise<void> {
-    const { error } = await getDb().from('shop_categories').delete().eq('id', id)
+    const { error } = await getDb().from(T.categories).delete().eq('id', id)
     if (error) throw error
   }
 
@@ -301,7 +410,7 @@ export class SupabaseShopProvider implements ShopProvider {
   async listOrders(options?: ListOrdersOptions): Promise<Order[]> {
     const db = getDb()
     const tenantId = getTenantId()
-    let q = db.from('shop_orders').select('*, items:shop_order_items(*)')
+    let q = db.from(T.orders).select(`*, items:${T.orderItems}(*)`)
     if (tenantId) q = q.eq('tenant_id', tenantId)
     if (options?.status) q = q.eq('status', options.status)
     if (options?.financialStatus) q = q.eq('financial_status', options.financialStatus)
@@ -318,7 +427,7 @@ export class SupabaseShopProvider implements ShopProvider {
 
   async getOrder(id: string): Promise<Order | null> {
     const { data, error } = await getDb()
-      .from('shop_orders').select('*, items:shop_order_items(*)')
+      .from(T.orders).select(`*, items:${T.orderItems}(*)`)
       .eq('id', id).maybeSingle()
     if (error) throw error
     return data ? rowToOrder(data) : null
@@ -332,12 +441,12 @@ export class SupabaseShopProvider implements ShopProvider {
     const shippingTotal = input.shippingTotal ?? 0
     const total = Math.round((subtotal - discountTotal + shippingTotal) * 100) / 100
     const { data: order, error: orderErr } = await db
-      .from('shop_orders')
+      .from(T.orders)
       .insert({ tenant_id: tenantId, customer_id: input.customerId ?? null, customer_name: input.customerName ?? null, customer_email: input.customerEmail ?? null, currency: input.currency ?? 'BRL', notes: input.notes ?? null, subtotal, discount_total: discountTotal, shipping_total: shippingTotal, discount_code: input.discountCode ?? null, total, status: 'open', financial_status: 'pending', fulfillment_status: 'unfulfilled' })
       .select().single()
     if (orderErr) throw orderErr
     const items = input.items.map(i => ({ order_id: order.id, product_id: asUuid(i.productId), name: i.name, sku: i.sku ?? null, quantity: i.quantity, unit_price: i.unitPrice, total: i.quantity * i.unitPrice, image_url: i.imageUrl ?? null }))
-    await db.from('shop_order_items').insert(items)
+    await db.from(T.orderItems).insert(items)
     return this.getOrder(order.id) as Promise<Order>
   }
 
@@ -347,11 +456,76 @@ export class SupabaseShopProvider implements ShopProvider {
     if (input.financialStatus !== undefined) updates.financial_status = input.financialStatus
     if (input.fulfillmentStatus !== undefined) updates.fulfillment_status = input.fulfillmentStatus
     if (input.notes !== undefined) updates.notes = input.notes
-    const { error } = await getDb().from('shop_orders').update(updates).eq('id', id)
+    const { error } = await getDb().from(T.orders).update(updates).eq('id', id)
     if (error) throw error
     return this.getOrder(id) as Promise<Order>
   }
 
+  // -------------------------------------------------------------------------
+  // Delivery zones
+  //
+  // Postal codes are stored as 8 bare digits so the range test in
+  // shop_quote_shipping is a plain BETWEEN. Accepting '22.041-001' from the
+  // form and normalising here means the merchant never has to think about it.
+  // -------------------------------------------------------------------------
+  async listShippingZones(): Promise<ShippingZone[]> {
+    const tenantId = getTenantId()
+    const { data, error } = await getDb()
+      .from(T.shippingZones)
+      .select('*')
+      .eq('tenant_id', tenantId)
+      .order('sort_order', { ascending: true })
+      .order('postal_from', { ascending: true })
+    if (error) throw error
+    return (data ?? []).map(rowToShippingZone)
+  }
+
+  async createShippingZone(input: CreateShippingZoneInput): Promise<ShippingZone> {
+    const tenantId = getTenantId()
+    if (!tenantId) throw new Error('@fayz-ai/shop: createShippingZone requires a tenant id.')
+    const { data, error } = await getDb()
+      .from(T.shippingZones)
+      .insert({ tenant_id: tenantId, ...shippingZonePayload(input) })
+      .select()
+      .single()
+    if (error) throw error
+    return rowToShippingZone(data)
+  }
+
+  async updateShippingZone(id: string, input: UpdateShippingZoneInput): Promise<ShippingZone> {
+    const { data, error } = await getDb()
+      .from(T.shippingZones)
+      .update(shippingZonePayload(input))
+      .eq('id', id)
+      .select()
+      .single()
+    if (error) throw error
+    return rowToShippingZone(data)
+  }
+
+  async deleteShippingZone(id: string): Promise<void> {
+    const { error } = await getDb().from(T.shippingZones).delete().eq('id', id)
+    if (error) throw error
+  }
+
+  /**
+   * Settle a pending order: the merchant confirming that the money arrived.
+   *
+   * Goes through the RPC rather than an UPDATE so the payment ledger row in
+   * public.transactions closes in the same transaction as the order — set
+   * financial_status by hand and the order says paid while the ledger still
+   * says pending. Since 0019 the RPC also enforces who may call it: a member of
+   * the owning tenant, or a PSP webhook with the service role.
+   */
+  async confirmPayment(id: string, reference?: string): Promise<Order | null> {
+    const { error } = await getDb().rpc('shop_confirm_payment', {
+      p_order_id: id,
+      p_reference: reference ?? null,
+    })
+    if (error) throw error
+    return this.getOrder(id)
+  }
+
   // Trusted placement — delegates all price/discount/inventory authority to the
   // shop_place_order RPC (SECURITY DEFINER). The browser never sets a price.
   async placeOrder(input: PlaceOrderInput): Promise<Order> {
@@ -366,7 +540,25 @@ export class SupabaseShopProvider implements ShopProvider {
       p_customer_email: input.customer?.email ?? null,
       p_currency: input.currency ?? 'BRL',
       p_discount_code: input.discountCode ?? null,
-      p_shipping_total: input.shippingTotal ?? 0,
+          p_shipping_total: input.shippingTotal ?? 0,
+      // snake_case keys on purpose: the RPC freezes this jsonb onto the
+      // order and public.addresses uses these exact column names.
+      p_shipping_address: input.shippingAddress
+        ? {
+        postal_code: input.shippingAddress.postalCode,
+        street: input.shippingAddress.street,
+        number: input.shippingAddress.number ?? null,
+        complement: input.shippingAddress.complement ?? null,
+        district: input.shippingAddress.district ?? null,
+        city: input.shippingAddress.city,
+        state: input.shippingAddress.state,
+        country: input.shippingAddress.country ?? 'BR',
+        recipient: input.shippingAddress.recipient ?? null,
+        phone: input.shippingAddress.phone ?? null,
+        label: input.shippingAddress.label ?? null,
+          }
+        : null,
+      p_payment_method: input.paymentMethod ?? null,
       p_notes: input.notes ?? null,
     })
     if (error) throw error
@@ -383,7 +575,7 @@ export class SupabaseShopProvider implements ShopProvider {
   async listCustomers(options?: ListCustomersOptions): Promise<ShopCustomer[]> {
     const db = getDb()
     const tenantId = getTenantId()
-    let q = db.from('shop_customers').select('*').order('first_name', { ascending: true })
+    let q = db.from(T.customers).select('*').order('first_name', { ascending: true })
     if (tenantId) q = q.eq('tenant_id', tenantId)
     if (options?.search) q = q.or(`first_name.ilike.%${options.search}%,last_name.ilike.%${options.search}%,email.ilike.%${options.search}%`)
     if (options?.limit) q = q.limit(options.limit)
@@ -393,14 +585,14 @@ export class SupabaseShopProvider implements ShopProvider {
   }
 
   async getCustomer(id: string): Promise<ShopCustomer | null> {
-    const { data, error } = await getDb().from('shop_customers').select('*').eq('id', id).maybeSingle()
+    const { data, error } = await getDb().from(T.customers).select('*').eq('id', id).maybeSingle()
     if (error) throw error
     return data ? rowToCustomer(data) : null
   }
 
   async createCustomer(input: CreateCustomerInput): Promise<ShopCustomer> {
     const { data, error } = await getDb()
-      .from('shop_customers')
+      .from(T.customers)
       .insert({ tenant_id: getTenantId(), first_name: input.firstName, last_name: input.lastName ?? '', email: input.email ?? null, phone: input.phone ?? null, notes: input.notes ?? null })
       .select().single()
     if (error) throw error
@@ -414,13 +606,13 @@ export class SupabaseShopProvider implements ShopProvider {
     if (input.email !== undefined) updates.email = input.email
     if (input.phone !== undefined) updates.phone = input.phone
     if (input.notes !== undefined) updates.notes = input.notes
-    const { data, error } = await getDb().from('shop_customers').update(updates).eq('id', id).select().single()
+    const { data, error } = await getDb().from(T.customers).update(updates).eq('id', id).select().single()
     if (error) throw error
     return rowToCustomer(data)
   }
 
   async deleteCustomer(id: string): Promise<void> {
-    const { error } = await getDb().from('shop_customers').delete().eq('id', id)
+    const { error } = await getDb().from(T.customers).delete().eq('id', id)
     if (error) throw error
   }
 
@@ -448,7 +640,7 @@ export class SupabaseShopProvider implements ShopProvider {
   async listDiscounts(options?: ListDiscountsOptions): Promise<Discount[]> {
     const db = getDb()
     const tenantId = getTenantId()
-    let q = db.from('shop_discounts').select('*').order('created_at', { ascending: false })
+    let q = db.from(T.discounts).select('*').order('created_at', { ascending: false })
     if (tenantId) q = q.eq('tenant_id', tenantId)
     if (options?.status) q = q.eq('status', options.status)
     if (options?.type) q = q.eq('type', options.type)
@@ -460,14 +652,14 @@ export class SupabaseShopProvider implements ShopProvider {
   }
 
   async getDiscount(id: string): Promise<Discount | null> {
-    const { data, error } = await getDb().from('shop_discounts').select('*').eq('id', id).maybeSingle()
+    const { data, error } = await getDb().from(T.discounts).select('*').eq('id', id).maybeSingle()
     if (error) throw error
     return data ? rowToDiscount(data) : null
   }
 
   async createDiscount(input: CreateDiscountInput): Promise<Discount> {
     const { data, error } = await getDb()
-      .from('shop_discounts')
+      .from(T.discounts)
       .insert({ tenant_id: getTenantId(), title: input.title, code: input.code ?? null, type: input.type, method: input.method ?? 'code', value: input.value, usage_limit: input.usageLimit ?? null, once_per_customer: input.oncePerCustomer ?? false, starts_at: input.startsAt ?? new Date().toISOString(), ends_at: input.endsAt ?? null, status: input.status ?? 'active', times_used: 0 })
       .select().single()
     if (error) throw error
@@ -483,13 +675,13 @@ export class SupabaseShopProvider implements ShopProvider {
     if (input.usageLimit !== undefined) updates.usage_limit = input.usageLimit
     if (input.status !== undefined) updates.status = input.status
     if (input.endsAt !== undefined) updates.ends_at = input.endsAt
-    const { data, error } = await getDb().from('shop_discounts').update(updates).eq('id', id).select().single()
+    const { data, error } = await getDb().from(T.discounts).update(updates).eq('id', id).select().single()
     if (error) throw error
     return rowToDiscount(data)
   }
 
   async deleteDiscount(id: string): Promise<void> {
-    const { error } = await getDb().from('shop_discounts').delete().eq('id', id)
+    const { error } = await getDb().from(T.discounts).delete().eq('id', id)
     if (error) throw error
   }
 }

package/src/tables.ts

@@ -0,0 +1,16 @@
+// Physical table names for @fayz-ai/shop. Renamed to the plg_shop_* industry-pool
+// prefix (was shop_*) when the core DB moved into the public schema. RPC function
+// names (shop_place_order, shop_get_order, shop_resolve_customer) are unchanged.
+export const T = {
+  products: 'plg_shop_products',
+  productImages: 'plg_shop_product_images',
+  categories: 'plg_shop_categories',
+  orders: 'plg_shop_orders',
+  orderItems: 'plg_shop_order_items',
+  customers: 'plg_shop_customers',
+  discounts: 'plg_shop_discounts',
+  // Core, not plg_shop_*: a delivery zone is a fact about the business, and
+  // fulfilment and financial read it too. Same reasoning as addresses and
+  // orders — see migration 0021.
+  shippingZones: 'shipping_zones',
+} as const

package/src/types.ts

@@ -191,6 +191,11 @@ export interface Order {
   customerEmail: string | null
   discountCode: string | null
   notes: string | null
+  /** Frozen delivery address captured at purchase time (0010/0012). */
+  shippingAddress: ShippingAddressSnapshot | null
+  /** How the buyer paid — opens the ledger row in public.transactions. */
+  paymentMethodKind: PaymentMethodKind | null
+  paidAt: string | null
   items: OrderItem[]
   createdAt: string
   updatedAt: string
@@ -266,6 +271,106 @@ export interface PlaceOrderLine {
  * storefront order. Prices, discount math, and inventory are resolved
  * server-side; the client supplies product ids, quantities, and intent only.
  */
+/** Structured delivery address. Mirrors public.addresses so the RPC can both
+ *  freeze it on the order and save it to the customer's address book. */
+export interface ShippingAddressInput {
+  postalCode: string
+  street: string
+  number?: string
+  complement?: string
+  district?: string
+  city: string
+  state: string
+  country?: string
+  recipient?: string
+  phone?: string
+  label?: string
+}
+
+export type PaymentMethodKind = 'pix' | 'credit_card' | 'debit_card' | 'boleto' | 'cash' | 'other'
+
+/**
+ * A range of postal codes the store delivers to, with its own price and ETA.
+ *
+ * `postalFrom`/`postalTo` are 8 digits, no punctuation. Ranges may overlap: the
+ * cheapest match wins, which is how a merchant layers a promotional zone over a
+ * broader one without deleting anything.
+ */
+export interface ShippingZone {
+  id: string
+  tenantId: string
+  name: string
+  carrier?: string | null
+  postalFrom: string
+  postalTo: string
+  rate: number
+  /** Overrides the store-wide free-delivery threshold inside this zone. */
+  freeAbove?: number | null
+  etaMinDays?: number | null
+  etaMaxDays?: number | null
+  active: boolean
+  sortOrder: number
+}
+
+export type CreateShippingZoneInput = Omit<ShippingZone, 'id' | 'tenantId'>
+export type UpdateShippingZoneInput = Partial<CreateShippingZoneInput>
+
+/**
+ * One delivery option for a postal code, as quoted by shop_quote_shipping.
+ *
+ * `rate` already has the zone's free-above threshold applied, so the caller
+ * never re-derives a price — the number shown is the number charged. An EMPTY
+ * list of options is the meaningful answer "we do not deliver there", not an
+ * error condition.
+ */
+export interface ShippingQuoteOption {
+  zoneId: string
+  name: string
+  carrier?: string
+  /** Resolved against the subtotal the quote was requested for. */
+  rate: number
+  /** The zone's price before any free-above rule — lets a caller re-resolve
+   *  `rate` for a changed cart without another round trip, using the same rule
+   *  the server applies. Without it a stale quote had to fall back to the
+   *  store-wide flat rate, which is a different zone's price. */
+  baseRate: number
+  freeAbove?: number | null
+  etaMinDays?: number
+  etaMaxDays?: number
+  /** True when the rate is 0 because the order cleared the zone's threshold. */
+  free: boolean
+}
+
+/**
+ * A row from the customer's address book (public.addresses).
+ *
+ * Only reachable with a signed-in shopper: the addresses_self_read policy joins
+ * plg_shop_customers.auth_user_id to auth.uid(), so an anonymous request sees
+ * nothing. Guests get an empty book and type their address, which is correct —
+ * the alternative is showing them somebody else's.
+ */
+export interface CustomerAddress extends ShippingAddressInput {
+  id: string
+  isDefault?: boolean
+}
+
+/** Address as stored on the order: snake_case, mirroring public.addresses. */
+export interface ShippingAddressSnapshot {
+  postal_code?: string
+  street?: string
+  number?: string
+  complement?: string
+  district?: string
+  city?: string
+  state?: string
+  country?: string
+  recipient?: string
+  phone?: string
+  label?: string
+  raw?: string
+  source?: string
+}
+
 export interface PlaceOrderInput {
   /** Tenant/store id. The Supabase provider falls back to the resolved shop tenant. */
   tenantId?: string
@@ -279,6 +384,11 @@ export interface PlaceOrderInput {
   discountCode?: string
   /** Shipping cost from the store's shipping policy. Clamped to >= 0 server-side. */
   shippingTotal?: number
+  /** Structured delivery address. Without it the address survives only as free
+   *  text in `notes`, which logistics cannot read. */
+  shippingAddress?: ShippingAddressInput
+  /** How the buyer is paying. Opens the ledger row in public.transactions. */
+  paymentMethod?: PaymentMethodKind
   items: PlaceOrderLine[]
 }