@core / contracts

1.0.0 ▾

1.0.0

已验证MIT

GitHub

GenPM 模块共享类型：内容、站点地图、搜索、后台资源、支付和追踪事件

代码10 个文件上下文约 532 个 token扫描通过

约 532 个 token→ src/lib/contracts/AGENTS.md→ .cursor/rules/genpm-core-contracts.mdc

这正是你的 AI 在 src/lib/contracts 中工作时读取的内容。不会向其上下文添加其他任何内容。

@core/contracts — rules for AI agents

Purpose

Types and small zod schemas shared by GenPM catalog modules, so a module can consume "anything that provides content / sitemap URLs / search documents / admin resources / payments" without importing the concrete module. No logic, no tables, no runtime dependency besides zod.

Map

index.ts — public API. Import from here only.
content.ts — ContentSource, ContentEntry (implemented by @core/content and CMS adapters).
sitemap.ts — SitemapSource (consumed by @core/seo).
search.ts — SearchSource, SearchDocument (consumed by @core/search).
admin.ts — AdminResource, AdminField (consumed by @core/admin).
payment.ts — PaymentProvider (implemented by @core/checkout, used by @core/orders).
events.ts — CommerceEvent, LeadEvent and their zod schemas (consumed by @core/pixels).
money.ts — Money (integer minor units + ISO 4217 code).

Integration

Usually installed as a dependency of another module; nothing to wire.
To expose your own data to the admin, sitemap or search, implement the type and register it in the project file the consuming module documents (src/genpm/admin.ts, src/genpm/seo.ts, src/genpm/search.ts):
```
import { defineSitemapSource } from './lib/contracts/index.ts';
export const projects = defineSitemapSource({ name: 'projects', async *urls() { yield { loc: '/projects' }; } });
```
Validate untrusted tracking payloads with TrackedEventSchema.parse(body) before forwarding them.

Conventions

Money is always { amount: integer minor units, currency: 'EUR' }; never floats.
Sources are async iterables: stream rows in pages, don't load whole tables into memory.
AdminResource.input validates create/update input; permissions are <resource>:<action> (posts:update).

Don't

Don't add implementations or helpers with behaviour here; put them in the module that owns the concept.
Don't change an existing type incompatibly: every catalog module depends on it (major version of the whole train).
Don't import other modules from this folder.

# @core/contracts — rules for AI agents

## Purpose
Types and small zod schemas shared by GenPM catalog modules, so a module can consume "anything that provides content /
sitemap URLs / search documents / admin resources / payments" without importing the concrete module. No logic, no
tables, no runtime dependency besides `zod`.

## Map
- `index.ts` — public API. Import from here only.
- `content.ts` — `ContentSource`, `ContentEntry` (implemented by @core/content and CMS adapters).
- `sitemap.ts` — `SitemapSource` (consumed by @core/seo).
- `search.ts` — `SearchSource`, `SearchDocument` (consumed by @core/search).
- `admin.ts` — `AdminResource`, `AdminField` (consumed by @core/admin).
- `payment.ts` — `PaymentProvider` (implemented by @core/checkout, used by @core/orders).
- `events.ts` — `CommerceEvent`, `LeadEvent` and their zod schemas (consumed by @core/pixels).
- `money.ts` — `Money` (integer minor units + ISO 4217 code).

## Integration
1. Usually installed as a dependency of another module; nothing to wire.
2. To expose your own data to the admin, sitemap or search, implement the type and register it in the project file
   the consuming module documents (`src/genpm/admin.ts`, `src/genpm/seo.ts`, `src/genpm/search.ts`):
   ```ts
   import { defineSitemapSource } from './lib/contracts/index.ts';
   export const projects = defineSitemapSource({ name: 'projects', async *urls() { yield { loc: '/projects' }; } });
   ```
3. Validate untrusted tracking payloads with `TrackedEventSchema.parse(body)` before forwarding them.

## Conventions
- Money is always `{ amount: integer minor units, currency: 'EUR' }`; never floats.
- Sources are async iterables: stream rows in pages, don't load whole tables into memory.
- `AdminResource.input` validates create/update input; permissions are `<resource>:<action>` (`posts:update`).

## Don't
- Don't add implementations or helpers with behaviour here; put them in the module that owns the concept.
- Don't change an existing type incompatibly: every catalog module depends on it (major version of the whole train).
- Don't import other modules from this folder.

应用 .genpmignore 后将被注入的确切目录树。固定于

src/lib/contracts/content.ts只读 · 7266529

// Fuente de contenido: lo implementan @core/content y los adaptadores (Payload, Keystatic); lo consumen blog,
// blocks, site y los kits sin saber de dónde viene el contenido.

export type ContentStatus = 'draft' | 'scheduled' | 'published' | 'archived';

export type ContentEntry<D = Record<string, unknown>> = {
  id: string;
  collection: string;
  slug: string;
  locale: string;
  status: ContentStatus;
  data: D;
  publishedAt: Date | null;
  updatedAt: Date;
};

export type ContentReadOptions = {
  /** Idioma pedido; sin entrada en ese idioma, la fuente devuelve la del idioma por defecto. */
  locale?: string;
  /** Incluir borradores (solo con un token de vista previa válido). */
  draft?: boolean;
};

export type ContentListQuery = ContentReadOptions & {
  limit?: number;
  offset?: number;
  /** Campo de orden: `publishedAt`, `updatedAt`, `slug` o un campo de `data`. Prefijo `-` = descendente. */
  orderBy?: string;
  /** Igualdad sobre campos de `data` (p. ej. `{ category: 'news' }`). */
  where?: Record<string, string | number | boolean | null>;
  /** El campo de `data` es una lista que contiene este valor (p. ej. `{ tags: 'news' }`). */
  contains?: Record<string, string>;
};

export interface ContentSource {
  getEntry<D = Record<string, unknown>>(
    collection: string,
    slug: string,
    opts?: ContentReadOptions,
  ): Promise<ContentEntry<D> | null>;
  listEntries<D = Record<string, unknown>>(collection: string, query?: ContentListQuery): Promise<ContentEntry<D>[]>;
}