Catálogo de produtos: variantes com opções, preços em centavos, categorias, coleções, traduções e reserva de estoque segura
Instalar
genpm add @core/catalogO que você recebe
- Código em src/lib/catalog/, 8 arquivos. (38,6 kB)
- Regras de IA em src/lib/catalog/AGENTS.md, mais arquivos de regras da IDE.
- Variáveis de ambiente adicionadas ao .env.example: STORE_CURRENCY.
- Resolve @core/contracts, @core/db, @core/money, @core/rich-text para você.
README
Este pacote não tem README.
Isto é exatamente o que sua IA lê quando trabalha em src/lib/catalog. Nada mais é adicionado ao contexto dela.
@core/catalog — rules for AI agents
Purpose
Products for a store: up to 3 options (Size, Color…) and their variants with SKU, price/compare-at/cost in minor
units, stock with backorder rules, weight and image; categories (tree), manual ordered collections, tags, attributes,
per-locale translations, media references (@core/media ids), sitemap/search sources and admin resources.
reserveStock locks the variant row so two buyers can't get the last unit. No cart, prices rules or multi-warehouse.
Map
index.ts— public API:createProduct,updateProduct,getProduct,listProducts,reserveStock,releaseStock,upsertCategory,setCollection,categoryTree,lowStockVariants,catalogAdminResources.products.ts— products, variants, listing, stock.taxonomy.ts— categories and collections.sources.ts—productSitemapSource,productSearchSource.admin.ts— admin resources.schema.ts— tables.
Integration
- Env:
STORE_CURRENCY(ISO code, defaultEUR). Migrations as insrc/lib/db/AGENTS.md. - Product page:
const p = await getProduct(slug, { locale })(404 when null); showp.variantswithformat(v.price, locale)(@core/money) andv.availability; renderp.descriptionwith @core/rich-text. - Listing:
listProducts({ category, tag, collection, sort, page, minPrice, maxPrice, inStock }). - Register
productSitemapSource()(seo),productSearchSource()(search) and...catalogAdminResources()(admin). - JSON-LD with
jsonLd.product(@core/seo) usingavailabilityand the real price. - Verify: create a product with two variants in the admin and see it at
/products/<slug>.
Conventions
- Prices are integers in
STORE_CURRENCY; the server price is the only valid price (carts recompute it). - Reserve stock only inside the order transaction (
reserveStock(id, qty, tx)); release it on cancel/expiry. - Archive products instead of deleting them: orders keep references to their variants.
- Permissions:
products:read|create|update|delete.
Don't
- Don't show a compare-at price that isn't real (the EU requires the lowest price of the last 30 days for discounts).
- Don't decrement
stockwith plain updates outsidereserveStock/releaseStock. - Don't expose
costAmountin public pages or APIs.
# @core/catalog — rules for AI agents
## Purpose
Products for a store: up to 3 options (Size, Color…) and their variants with SKU, price/compare-at/cost in minor
units, stock with backorder rules, weight and image; categories (tree), manual ordered collections, tags, attributes,
per-locale translations, media references (@core/media ids), sitemap/search sources and admin resources.
`reserveStock` locks the variant row so two buyers can't get the last unit. No cart, prices rules or multi-warehouse.
## Map
- `index.ts` — public API: `createProduct`, `updateProduct`, `getProduct`, `listProducts`, `reserveStock`, `releaseStock`, `upsertCategory`, `setCollection`, `categoryTree`, `lowStockVariants`, `catalogAdminResources`.
- `products.ts` — products, variants, listing, stock. `taxonomy.ts` — categories and collections.
- `sources.ts` — `productSitemapSource`, `productSearchSource`. `admin.ts` — admin resources. `schema.ts` — tables.
## Integration
1. Env: `STORE_CURRENCY` (ISO code, default `EUR`). Migrations as in `src/lib/db/AGENTS.md`.
2. Product page: `const p = await getProduct(slug, { locale })` (404 when null); show `p.variants` with
`format(v.price, locale)` (@core/money) and `v.availability`; render `p.description` with @core/rich-text.
3. Listing: `listProducts({ category, tag, collection, sort, page, minPrice, maxPrice, inStock })`.
4. Register `productSitemapSource()` (seo), `productSearchSource()` (search) and `...catalogAdminResources()` (admin).
5. JSON-LD with `jsonLd.product` (@core/seo) using `availability` and the real price.
6. Verify: create a product with two variants in the admin and see it at `/products/<slug>`.
## Conventions
- Prices are integers in `STORE_CURRENCY`; the server price is the only valid price (carts recompute it).
- Reserve stock only inside the order transaction (`reserveStock(id, qty, tx)`); release it on cancel/expiry.
- Archive products instead of deleting them: orders keep references to their variants.
- Permissions: `products:read|create|update|delete`.
## Don't
- Don't show a compare-at price that isn't real (the EU requires the lowest price of the last 30 days for discounts).
- Don't decrement `stock` with plain updates outside `reserveStock`/`releaseStock`.
- Don't expose `costAmount` in public pages or APIs.
A árvore exata que será injetada, após o .genpmignore. Fixada em
// Categorías (árbol) y colecciones manuales ordenadas.
import { asc, eq } from 'drizzle-orm';
import { z } from 'zod';
import { type Executor, getDb, withTransaction } from '../db/index.ts';
import { CatalogError } from './products.ts';
import { type Category, categories, collectionProducts, collections, products } from './schema.ts';
const Slug = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/).max(120);
export const CategoryInput = z.object({
slug: Slug,
name: z.string().min(1).max(120),
description: z.string().max(1000).nullish(),
parent: Slug.nullish(),
position: z.number().int().default(0),
translations: z.record(z.string(), z.object({ name: z.string().max(120).optional(), description: z.string().max(1000).optional() })).default({}),
});
/** Crea o actualiza (por slug) una categoría. Rechaza ciclos en el árbol. */
export async function upsertCategory(input: z.input<typeof CategoryInput>, db: Executor = getDb()): Promise<Category> {
const c = CategoryInput.parse(input);
let parentId: string | null = null;
if (c.parent) {
const all = await db.select().from(categories);
const parent = all.find((x) => x.slug === c.parent);
if (!parent) throw new CatalogError('invalid', `unknown parent ${c.parent}`);
for (let cur: Category | undefined = parent; cur; cur = all.find((x) => x.id === cur!.parentId))
if (cur.slug === c.slug) throw new CatalogError('invalid', 'category cycle');
parentId = parent.id;
}
const values = { slug: c.slug, name: c.name, description: c.description ?? null, parentId, position: c.position, translations: c.translations };
const [row] = await db.insert(categories).values(values).onConflictDoUpdate({ target: categories.slug, set: values }).returning();
return row!;
}
export type CategoryNode = Category & { children: CategoryNode[] };
/** Árbol completo de categorías ordenado por `position`. */
export async function categoryTree(db: Executor = getDb()): Promise<CategoryNode[]> {
const all = await db.select().from(categories).orderBy(asc(categories.position), asc(categories.name));
const nodes = new Map(all.map((c) => [c.id, { ...c, children: [] as CategoryNode[] }]));
const roots: CategoryNode[] = [];
for (const n of nodes.values()) (n.parentId && nodes.get(n.parentId) ? nodes.get(n.parentId)!.children : roots).push(n);
return roots;
}
/** Crea o actualiza una colección y fija sus productos en el orden dado (por slug de producto). */
export async function setCollection(input: { slug: string; name: string; description?: string | null; products: string[] }, db = getDb()) {
const slug = Slug.parse(input.slug);
return withTransaction(async (tx) => {
const values = { slug, name: input.name.slice(0, 120), description: input.description ?? null };
const [col] = await tx.insert(collections).values(values).onConflictDoUpdate({ target: collections.slug, set: values }).returning();
await tx.delete(collectionProducts).where(eq(collectionProducts.collectionId, col!.id));
const rows = await tx.select({ id: products.id, slug: products.slug }).from(products);
const items = input.products.map((s, position) => {
const p = rows.find((r) => r.slug === s);
if (!p) throw new CatalogError('invalid', `unknown product ${s}`);
return { collectionId: col!.id, productId: p.id, position };
});
if (items.length) await tx.insert(collectionProducts).values(items);
return col!;
}, db);
}
Este pacote não declara servidores MCP.
| Versão | Commit | Publicado | Análise |
|---|---|---|---|
| 1.0.0 | 79d3468 | há 7 horas | análise aprovada |
- npm
- zod ^4.0.0
- proposto
- O GenPM propõe o comando npm e só o executa se você disser sim.
- análise
- análise aprovada · 0 achados
- commit
- v1.0.0 → 79d3468925acbde57d17a18a32e9d4bdefc28b5e · verificado após o download
- scripts
- Nenhum. O GenPM nunca executa código de pacotes.
- licença
- MIT
- Qualidade
- 100/100
- Licença reconhecidacumprido
- AGENTS.md explica o propósitocumprido
- AGENTS.md tem passos de integraçãocumprido
- AGENTS.md lista convenções ou proibiçõescumprido
- Inclui testescumprido
- Escaneamento de segurança aprovadocumprido
- Publicado nos últimos 6 mesescumprido
- Publicador verificadocumprido
- Resumo e palavras-chavecumprido
- denúncia
- Viu algo errado?