@notheadless/sdk

Tipado seguro

Cada select se convierte en un parámetro fields=, y el tipo del resultado son exactamente los campos que seleccionaste. Sin casts ni tipos con todo opcional.

La selección acota el resultado

const rows = await nube.products.findMany({ select: { id: true, variants: true } })
rows[0].variants[0].price   // string | null
rows[0].name                // ✗ Property 'name' does not exist

const def = await nube.products.findUnique({ where: { id: 1 } })
//    ^? { id: number; name: string; handle: string } | null   ← campos por defecto de la API

nube.products.findMany({ select: { id: true, nmae: true } })
//                                            ~~~~ ✗ Type 'true' is not assignable to type 'never'

Selecciones reutilizables

Definí una selección una sola vez e inferí el tipo de su payload, como con InferSelectModel de Drizzle. defineSelect conserva los tipos literales sin as const:

lib/catalog.ts

import { defineSelect, type InferProduct } from "@notheadless/sdk"

export const productCardSelect = defineSelect.product({
  id: true, name: true, handle: true, images: true, variants: true,
})
export type CardProduct = InferProduct<typeof productCardSelect>

export const productDetailSelect = defineSelect.product({
  ...productCardSelect,
  description: true,
  seoTitle: true,
})

Modelos normalizados

Las respuestas se normalizan para que los tipos sean simples y honestos:

camelCase en todos lados: promotional_price → promotionalPrice, stock_management → stockManagement.
Los strings localizados ({ es: "…" }) se resuelven a strings planos según locale.
tags pasa a ser string[]. Los values de las variantes y los attributes de los productos siempre son string[].
Los montos se mantienen como string decimal sin pérdida ("29900.00") o null. Un precio faltante nunca se convierte en 0.
custom_fields pasa tal cual, sin modificaciones.

Los mapeos de campos entre modelo y API usan satisfies Record<keyof Product, string>, así que el propio SDK no puede desalinearse de sus tipos: si agregás un campo al modelo sin mapearlo, falla la compilación.

Tipos exportados

import type {
  Product, Variant, ProductImage, ProductCategory, Category, InventoryLevel,
  ShippingOption, Checkout, CheckoutLineItem, Pagination, Page, ProductSort,
  ProductSelect, CategorySelect, Selected, InferProduct, InferCategory,
  CartValidation, CartIssue, NubeErrorCode,
} from "@notheadless/sdk"

Cargando documentación…

La selección acota el resultado

const rows = await nube.products.findMany({ select: { id: true, variants: true } })
rows[0].variants[0].price   // string | null
rows[0].name                // ✗ Property 'name' does not exist

const def = await nube.products.findUnique({ where: { id: 1 } })
//    ^? { id: number; name: string; handle: string } | null   ← campos por defecto de la API

nube.products.findMany({ select: { id: true, nmae: true } })
//                                            ~~~~ ✗ Type 'true' is not assignable to type 'never'

Selecciones reutilizables

Definí una selección una sola vez e inferí el tipo de su payload, como con InferSelectModel de Drizzle. defineSelect conserva los tipos literales sin as const:

lib/catalog.ts

import { defineSelect, type InferProduct } from "@notheadless/sdk"

export const productCardSelect = defineSelect.product({
  id: true, name: true, handle: true, images: true, variants: true,
})
export type CardProduct = InferProduct<typeof productCardSelect>

export const productDetailSelect = defineSelect.product({
  ...productCardSelect,
  description: true,
  seoTitle: true,
})

Modelos normalizados

Las respuestas se normalizan para que los tipos sean simples y honestos:

camelCase en todos lados: promotional_price → promotionalPrice, stock_management → stockManagement.

Los strings localizados ({ es: "…" }) se resuelven a strings planos según locale.

tags pasa a ser string[]. Los values de las variantes y los attributes de los productos siempre son string[].

Los montos se mantienen como string decimal sin pérdida ("29900.00") o null. Un precio faltante nunca se convierte en 0.

custom_fields pasa tal cual, sin modificaciones.

Tipos exportados

import type {
  Product, Variant, ProductImage, ProductCategory, Category, InventoryLevel,
  ShippingOption, Checkout, CheckoutLineItem, Pagination, Page, ProductSort,
  ProductSelect, CategorySelect, Selected, InferProduct, InferCategory,
  CartValidation, CartIssue, NubeErrorCode,
} from "@notheadless/sdk"