@core / cart

1.1.0 ▾

1.1.0

verificadoMIT

GitHub

Carrinho: cookie assinado de visitante, fusão no login, preços no servidor e cálculo de totais extensível

Código10 arquivosContexto~611 tokensanálise aprovada

~611 tokens→ src/lib/cart/AGENTS.md→ .cursor/rules/genpm-core-cart.mdc

Isto é exatamente o que sua IA lê quando trabalha em src/lib/cart. Nada mais é adicionado ao contexto dela.

@core/cart — rules for AI agents

Purpose

Carts for guests (id in an HMAC-signed HttpOnly cookie) and users (merged on login), lines per variant with stock and quantity checks, and computeTotals: lines are always priced from @core/catalog in the database, unavailable items are dropped with an issues entry, then registered steps run (discounts 100, shipping 200, taxes 300). No payments or orders. Tables: carts, cart_lines.

Map

index.ts — public API: getCart, getOrCreateCart, addLine, setLine, setDiscountCodes, setCartMeta, computeTotals, registerTotalsStep, applyOrderDiscount, registerPendingCodeUses, pendingCodeUses, pruneCarts.
cart.ts — operations. totals.ts — pipeline and types. cookie.ts — signed cookie.
adapters/hono.ts — cartRoutes({ currentUserId }). adapters/next.ts — cartRoute, cartLinesRoute, cartLineRoute, cartCodesRoute.

Integration

Env: CART_COOKIE_SECRET (≥ 32 chars). Migrations as in src/lib/db/AGENTS.md.
Mount the JSON API at /api/cart with currentUserId from @core/auth (or async () => null for guest-only shops). Calls: GET /api/cart, POST /api/cart/lines {variantId, quantity}, PUT /api/cart/lines/:variantId {quantity} (0 removes), PUT /api/cart/codes {codes}.
Server pages: const cart = await getCart(cookieHeader, userId); const totals = cart && await computeTotals(cart).
Modules that change totals register a step once at startup: registerTotalsStep({ name, order, run: (t) => … }); order discounts must go through applyOrderDiscount so they are allocated to lines. Modules that open payments before the order exists (@core/checkout) register registerPendingCodeUses so usage-limited codes (@core/discounts) count in-flight payments as reserved.
Schedule pruneCarts() daily (@core/jobs; with kit-store, its store.maintenance job does it).
Verify: add a product, change its price in the admin, the cart shows the new price.

Conventions

Totals shown and charged come from computeTotals only; never from values sent by the browser.
Show every issues entry to the customer before checkout.
Money values are { amount, currency } in minor units (@core/money).

Don't

Don't reserve stock in the cart (that happens when the order is created).
Don't trust prices, discounts or totals in request bodies, and don't read the cart cookie without verifying it.

# @core/cart — rules for AI agents

## Purpose
Carts for guests (id in an HMAC-signed HttpOnly cookie) and users (merged on login), lines per variant with stock
and quantity checks, and `computeTotals`: lines are always priced from @core/catalog in the database, unavailable
items are dropped with an `issues` entry, then registered steps run (discounts 100, shipping 200, taxes 300).
No payments or orders. Tables: `carts`, `cart_lines`.

## Map
- `index.ts` — public API: `getCart`, `getOrCreateCart`, `addLine`, `setLine`, `setDiscountCodes`, `setCartMeta`, `computeTotals`, `registerTotalsStep`, `applyOrderDiscount`, `registerPendingCodeUses`, `pendingCodeUses`, `pruneCarts`.
- `cart.ts` — operations. `totals.ts` — pipeline and types. `cookie.ts` — signed cookie.
- `adapters/hono.ts` — `cartRoutes({ currentUserId })`. `adapters/next.ts` — `cartRoute`, `cartLinesRoute`, `cartLineRoute`, `cartCodesRoute`.

## Integration
1. Env: `CART_COOKIE_SECRET` (≥ 32 chars). Migrations as in `src/lib/db/AGENTS.md`.
2. Mount the JSON API at `/api/cart` with `currentUserId` from @core/auth (or `async () => null` for guest-only shops).
   Calls: `GET /api/cart`, `POST /api/cart/lines {variantId, quantity}`, `PUT /api/cart/lines/:variantId {quantity}` (0 removes), `PUT /api/cart/codes {codes}`.
3. Server pages: `const cart = await getCart(cookieHeader, userId); const totals = cart && await computeTotals(cart)`.
4. Modules that change totals register a step once at startup: `registerTotalsStep({ name, order, run: (t) => … })`;
   order discounts must go through `applyOrderDiscount` so they are allocated to lines.
   Modules that open payments before the order exists (@core/checkout) register `registerPendingCodeUses` so
   usage-limited codes (@core/discounts) count in-flight payments as reserved.
5. Schedule `pruneCarts()` daily (@core/jobs; with kit-store, its `store.maintenance` job does it).
6. Verify: add a product, change its price in the admin, the cart shows the new price.

## Conventions
- Totals shown and charged come from `computeTotals` only; never from values sent by the browser.
- Show every `issues` entry to the customer before checkout.
- Money values are `{ amount, currency }` in minor units (@core/money).

## Don't
- Don't reserve stock in the cart (that happens when the order is created).
- Don't trust prices, discounts or totals in request bodies, and don't read the cart cookie without verifying it.

A árvore exata que será injetada, após o .genpmignore. Fixada em

src/lib/cart/schema.tssomente leitura · 787ea88

// Tablas de @core/cart. Las recoge drizzle-kit vía src/lib/db/drizzle.config.ts.
import { index, integer, jsonb, pgTable, primaryKey, text, timestamp } from 'drizzle-orm/pg-core';
import { users } from '../auth/index.ts';
import { productVariants } from '../catalog/index.ts';
import { primaryId, timestamps } from '../db/index.ts';

export const carts = pgTable(
  'carts',
  {
    id: primaryId('crt'),
    userId: text('user_id').references(() => users.id, { onDelete: 'cascade' }),
    currency: text('currency').notNull(),
    /** Códigos introducidos por el cliente (los valida @core/discounts al calcular). */
    discountCodes: jsonb('discount_codes').$type<string[]>().notNull().default([]),
    /** Datos que eligen otros pasos (tarifa de envío, país…). */
    meta: jsonb('meta').$type<Record<string, string>>().notNull().default({}),
    expiresAt: timestamp('expires_at', { withTimezone: true, mode: 'date' }).notNull(),
    ...timestamps,
  },
  (t) => [index('carts_user_idx').on(t.userId), index('carts_expires_idx').on(t.expiresAt)],
);

export const cartLines = pgTable(
  'cart_lines',
  {
    cartId: text('cart_id')
      .notNull()
      .references(() => carts.id, { onDelete: 'cascade' }),
    variantId: text('variant_id')
      .notNull()
      .references(() => productVariants.id, { onDelete: 'cascade' }),
    quantity: integer('quantity').notNull(),
    ...timestamps,
  },
  (t) => [primaryKey({ columns: [t.cartId, t.variantId] })],
);

export type Cart = typeof carts.$inferSelect;