digital-products 2.1.3 → 2.3.0

package/dist/types.d.ts

@@ -1,9 +1,795 @@
 /**
- * Core types for digital products
+ * @packageDocumentation
+ * @module digital-products
+ *
+ * Digital product types for schema.org.ai
+ *
+ * This package provides product types using JSON-LD conventions:
+ * - {@link Product} - Base product interface
+ * - {@link App} - Application (web, mobile, desktop)
+ * - {@link API} - API with versioning and auth
+ * - {@link Site} - Website (marketing, docs, blog)
+ * - {@link Service} - Backend service
+ * - {@link Feature} - Product feature with lifecycle
+ *
+ * All types use `$id` and `$type` fields (JSON-LD style).
+ *
+ * ## Unified Types (Recommended)
+ *
+ * The unified types use JSON-LD conventions with `$id` and `$type`:
+ *
+ * @example
+ * ```typescript
+ * import { createApp, isApp, AppSchema } from 'digital-products'
+ *
+ * const app = createApp({
+ *   $id: 'my-app',
+ *   name: 'My App',
+ *   description: 'An app',
+ *   platform: 'web',
+ *   url: 'https://example.com'
+ * })
+ *
+ * if (isApp(data)) {
+ *   console.log(data.platform)
+ * }
+ * ```
+ *
+ * ## Legacy Definition Types
+ *
+ * The `*Definition` types (AppDefinition, APIDefinition, etc.) are maintained
+ * for backwards compatibility. New code should use the unified types.
  */
-import type { SimpleSchema } from 'ai-functions';
+import { z } from 'zod';
+type SimpleSchema = Record<string, unknown>;
 /**
- * Base digital product definition
+ * Product - Base interface for digital products
+ *
+ * All digital products (App, API, Site, Service) extend this base.
+ * Uses JSON-LD conventions with `$id` and `$type`.
+ *
+ * The `$id` field is a unique identifier URI for the product.
+ * The `$type` field identifies this as a Product type.
+ *
+ * @see https://schema.org.ai/Product
+ *
+ * @example
+ * ```typescript
+ * const product = createProduct({
+ *   $id: 'https://schema.org.ai/products/acme',
+ *   name: 'Acme Product',
+ *   description: 'A digital product'
+ * })
+ * // product.status === 'active' (default)
+ * // product.$type === 'https://schema.org.ai/Product'
+ * ```
+ */
+export interface Product {
+    /** Unique identifier URI (JSON-LD `@id` equivalent) */
+    $id: string;
+    /** Type URI (JSON-LD `@type` equivalent) */
+    $type: 'https://schema.org.ai/Product';
+    /** Human-readable name */
+    name: string;
+    /** Description of the product */
+    description: string;
+    /** Product status - defaults to 'active' when created via factory */
+    status: 'active' | 'inactive' | 'archived';
+}
+/**
+ * Zod schema for validating Product objects
+ *
+ * Use this schema for runtime validation of Product data.
+ *
+ * @see {@link Product}
+ * @see {@link isProduct}
+ *
+ * @example
+ * ```typescript
+ * const result = ProductSchema.safeParse(data)
+ * if (result.success) {
+ *   console.log(result.data.name)
+ * }
+ * ```
+ */
+export declare const ProductSchema: z.ZodObject<{
+    $id: z.ZodString;
+    $type: z.ZodLiteral<"https://schema.org.ai/Product">;
+    name: z.ZodString;
+    description: z.ZodString;
+    status: z.ZodEnum<["active", "inactive", "archived"]>;
+}, "strip", z.ZodTypeAny, {
+    $id: string;
+    $type: "https://schema.org.ai/Product";
+    status: "active" | "inactive" | "archived";
+    name: string;
+    description: string;
+}, {
+    $id: string;
+    $type: "https://schema.org.ai/Product";
+    status: "active" | "inactive" | "archived";
+    name: string;
+    description: string;
+}>;
+/**
+ * Type guard to check if an object is a valid Product
+ *
+ * Uses Zod schema validation under the hood for comprehensive checking.
+ *
+ * @param obj - Object to validate
+ * @returns True if valid Product (JSON-LD style with $id/$type)
+ *
+ * @see {@link Product}
+ * @see {@link ProductSchema}
+ *
+ * @example
+ * ```typescript
+ * if (isProduct(data)) {
+ *   // TypeScript knows data is Product here
+ *   console.log(data.$id, data.name)
+ * }
+ * ```
+ */
+export declare function isProduct(obj: unknown): obj is Product;
+/**
+ * Factory function to create a new Product
+ *
+ * Automatically sets `$type` to 'https://schema.org.ai/Product' and
+ * defaults `status` to 'active' if not provided.
+ *
+ * @param input - Product data (status defaults to 'active')
+ * @returns Complete Product with $type auto-filled
+ *
+ * @see {@link Product}
+ *
+ * @example
+ * ```typescript
+ * const product = createProduct({
+ *   $id: 'https://schema.org.ai/products/acme',
+ *   name: 'Acme Product',
+ *   description: 'A digital product'
+ * })
+ * // product.status === 'active'
+ * // product.$type === 'https://schema.org.ai/Product'
+ * ```
+ */
+export declare function createProduct(input: Omit<Product, '$type' | 'status'> & {
+    status?: Product['status'];
+}): Product;
+/**
+ * App - Application product (web, mobile, desktop)
+ *
+ * Interactive user-facing applications that run on various platforms
+ * including web browsers, mobile devices, and desktops.
+ *
+ * Extends {@link Product} with platform-specific fields.
+ *
+ * @see https://schema.org.ai/App
+ *
+ * @example
+ * ```typescript
+ * const app = createApp({
+ *   $id: 'https://schema.org.ai/apps/dashboard',
+ *   name: 'Dashboard',
+ *   description: 'Admin dashboard',
+ *   platform: 'web',
+ *   url: 'https://dashboard.example.com'
+ * })
+ * // app.$type === 'https://schema.org.ai/App'
+ * // app.status === 'active' (default)
+ * ```
+ */
+export interface App extends Omit<Product, '$type'> {
+    /** Type URI for App (JSON-LD `@type` equivalent) */
+    $type: 'https://schema.org.ai/App';
+    /** Platform the app runs on - web, mobile, desktop, or api */
+    platform: 'web' | 'mobile' | 'desktop' | 'api';
+    /** URL where the app is hosted or accessible */
+    url: string;
+}
+/**
+ * Zod schema for validating App objects
+ *
+ * Use this schema for runtime validation of App data.
+ *
+ * @see {@link App}
+ * @see {@link isApp}
+ *
+ * @example
+ * ```typescript
+ * const result = AppSchema.safeParse(data)
+ * if (result.success) {
+ *   console.log(result.data.platform, result.data.url)
+ * }
+ * ```
+ */
+export declare const AppSchema: z.ZodObject<{
+    $id: z.ZodString;
+    $type: z.ZodLiteral<"https://schema.org.ai/App">;
+    name: z.ZodString;
+    description: z.ZodString;
+    status: z.ZodEnum<["active", "inactive", "archived"]>;
+    platform: z.ZodEnum<["web", "mobile", "desktop", "api"]>;
+    url: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    $id: string;
+    $type: "https://schema.org.ai/App";
+    status: "active" | "inactive" | "archived";
+    name: string;
+    description: string;
+    platform: "web" | "mobile" | "desktop" | "api";
+    url: string;
+}, {
+    $id: string;
+    $type: "https://schema.org.ai/App";
+    status: "active" | "inactive" | "archived";
+    name: string;
+    description: string;
+    platform: "web" | "mobile" | "desktop" | "api";
+    url: string;
+}>;
+/**
+ * Type guard to check if an object is a valid App
+ *
+ * Uses Zod schema validation under the hood.
+ *
+ * @param obj - Object to validate
+ * @returns True if valid App (JSON-LD style with $id/$type and platform/url)
+ *
+ * @see {@link App}
+ * @see {@link AppSchema}
+ *
+ * @example
+ * ```typescript
+ * if (isApp(data)) {
+ *   // TypeScript knows data is App here
+ *   console.log(data.platform, data.url)
+ * }
+ * ```
+ */
+export declare function isApp(obj: unknown): obj is App;
+/**
+ * Factory function to create a new App
+ *
+ * Automatically sets `$type` to 'https://schema.org.ai/App' and
+ * defaults `status` to 'active' if not provided.
+ *
+ * @param input - App data (status defaults to 'active')
+ * @returns Complete App with $type auto-filled
+ *
+ * @see {@link App}
+ *
+ * @example
+ * ```typescript
+ * const app = createApp({
+ *   $id: 'https://schema.org.ai/apps/dashboard',
+ *   name: 'Dashboard',
+ *   description: 'Admin dashboard',
+ *   platform: 'web',
+ *   url: 'https://dashboard.example.com'
+ * })
+ * ```
+ */
+export declare function createApp(input: Omit<App, '$type' | 'status'> & {
+    status?: App['status'];
+}): App;
+/**
+ * API - API product with versioning and auth
+ *
+ * Programmatic interfaces for other software to consume.
+ * Includes versioning and authentication configuration.
+ *
+ * Extends {@link Product} with API-specific fields.
+ *
+ * @see https://schema.org.ai/API
+ *
+ * @example
+ * ```typescript
+ * const api = createAPI({
+ *   $id: 'https://schema.org.ai/apis/users',
+ *   name: 'Users API',
+ *   description: 'User management API',
+ *   baseUrl: 'https://api.example.com/v1',
+ *   version: '1.0.0',
+ *   authentication: 'bearer'
+ * })
+ * // api.$type === 'https://schema.org.ai/API'
+ * ```
+ */
+export interface API extends Omit<Product, '$type'> {
+    /** Type URI for API (JSON-LD `@type` equivalent) */
+    $type: 'https://schema.org.ai/API';
+    /** Base URL for API endpoints */
+    baseUrl: string;
+    /** API version string (e.g., '1.0.0', 'v2') */
+    version: string;
+    /** Authentication method - bearer token, API key, OAuth, or none */
+    authentication: 'bearer' | 'api_key' | 'oauth' | 'none';
+}
+/**
+ * Zod schema for validating API objects
+ *
+ * Use this schema for runtime validation of API data.
+ *
+ * @see {@link API}
+ * @see {@link isAPI}
+ *
+ * @example
+ * ```typescript
+ * const result = APISchema.safeParse(data)
+ * if (result.success) {
+ *   console.log(result.data.baseUrl, result.data.version)
+ * }
+ * ```
+ */
+export declare const APISchema: z.ZodObject<{
+    $id: z.ZodString;
+    $type: z.ZodLiteral<"https://schema.org.ai/API">;
+    name: z.ZodString;
+    description: z.ZodString;
+    status: z.ZodEnum<["active", "inactive", "archived"]>;
+    baseUrl: z.ZodString;
+    version: z.ZodString;
+    authentication: z.ZodEnum<["bearer", "api_key", "oauth", "none"]>;
+}, "strip", z.ZodTypeAny, {
+    $id: string;
+    $type: "https://schema.org.ai/API";
+    status: "active" | "inactive" | "archived";
+    name: string;
+    description: string;
+    baseUrl: string;
+    version: string;
+    authentication: "bearer" | "api_key" | "oauth" | "none";
+}, {
+    $id: string;
+    $type: "https://schema.org.ai/API";
+    status: "active" | "inactive" | "archived";
+    name: string;
+    description: string;
+    baseUrl: string;
+    version: string;
+    authentication: "bearer" | "api_key" | "oauth" | "none";
+}>;
+/**
+ * Type guard to check if an object is a valid API
+ *
+ * Uses Zod schema validation under the hood.
+ *
+ * @param obj - Object to validate
+ * @returns True if valid API (JSON-LD style with baseUrl, version, authentication)
+ *
+ * @see {@link API}
+ * @see {@link APISchema}
+ *
+ * @example
+ * ```typescript
+ * if (isAPI(data)) {
+ *   // TypeScript knows data is API here
+ *   console.log(data.baseUrl, data.authentication)
+ * }
+ * ```
+ */
+export declare function isAPI(obj: unknown): obj is API;
+/**
+ * Factory function to create a new API
+ *
+ * Automatically sets `$type` to 'https://schema.org.ai/API' and
+ * defaults `status` to 'active' if not provided.
+ *
+ * @param input - API data (status defaults to 'active')
+ * @returns Complete API with $type auto-filled
+ *
+ * @see {@link API}
+ *
+ * @example
+ * ```typescript
+ * const api = createAPI({
+ *   $id: 'https://schema.org.ai/apis/users',
+ *   name: 'Users API',
+ *   description: 'User management API',
+ *   baseUrl: 'https://api.example.com/v1',
+ *   version: '1.0.0',
+ *   authentication: 'bearer'
+ * })
+ * ```
+ */
+export declare function createAPI(input: Omit<API, '$type' | 'status'> & {
+    status?: API['status'];
+}): API;
+/**
+ * Site - Website product (marketing, docs, blog)
+ *
+ * Content-focused websites including marketing pages, documentation sites,
+ * blogs, and web applications.
+ *
+ * Extends {@link Product} with site-specific fields.
+ *
+ * @see https://schema.org.ai/Site
+ *
+ * @example
+ * ```typescript
+ * const site = createSite({
+ *   $id: 'https://schema.org.ai/sites/docs',
+ *   name: 'Documentation',
+ *   description: 'Product documentation site',
+ *   url: 'https://docs.example.com',
+ *   siteType: 'docs'
+ * })
+ * // site.$type === 'https://schema.org.ai/Site'
+ * ```
+ */
+export interface Site extends Omit<Product, '$type'> {
+    /** Type URI for Site (JSON-LD `@type` equivalent) */
+    $type: 'https://schema.org.ai/Site';
+    /** URL of the site */
+    url: string;
+    /** Type of website - marketing, docs, blog, or app */
+    siteType: 'marketing' | 'docs' | 'blog' | 'app';
+}
+/**
+ * Zod schema for validating Site objects
+ *
+ * Use this schema for runtime validation of Site data.
+ *
+ * @see {@link Site}
+ * @see {@link isSite}
+ *
+ * @example
+ * ```typescript
+ * const result = SiteSchema.safeParse(data)
+ * if (result.success) {
+ *   console.log(result.data.url, result.data.siteType)
+ * }
+ * ```
+ */
+export declare const SiteSchema: z.ZodObject<{
+    $id: z.ZodString;
+    $type: z.ZodLiteral<"https://schema.org.ai/Site">;
+    name: z.ZodString;
+    description: z.ZodString;
+    status: z.ZodEnum<["active", "inactive", "archived"]>;
+    url: z.ZodString;
+    siteType: z.ZodEnum<["marketing", "docs", "blog", "app"]>;
+}, "strip", z.ZodTypeAny, {
+    $id: string;
+    $type: "https://schema.org.ai/Site";
+    status: "active" | "inactive" | "archived";
+    name: string;
+    description: string;
+    url: string;
+    siteType: "marketing" | "docs" | "blog" | "app";
+}, {
+    $id: string;
+    $type: "https://schema.org.ai/Site";
+    status: "active" | "inactive" | "archived";
+    name: string;
+    description: string;
+    url: string;
+    siteType: "marketing" | "docs" | "blog" | "app";
+}>;
+/**
+ * Type guard to check if an object is a valid Site
+ *
+ * Uses Zod schema validation under the hood.
+ *
+ * @param obj - Object to validate
+ * @returns True if valid Site (JSON-LD style with url and siteType)
+ *
+ * @see {@link Site}
+ * @see {@link SiteSchema}
+ *
+ * @example
+ * ```typescript
+ * if (isSite(data)) {
+ *   // TypeScript knows data is Site here
+ *   console.log(data.url, data.siteType)
+ * }
+ * ```
+ */
+export declare function isSite(obj: unknown): obj is Site;
+/**
+ * Factory function to create a new Site
+ *
+ * Automatically sets `$type` to 'https://schema.org.ai/Site' and
+ * defaults `status` to 'active' if not provided.
+ *
+ * @param input - Site data (status defaults to 'active')
+ * @returns Complete Site with $type auto-filled
+ *
+ * @see {@link Site}
+ *
+ * @example
+ * ```typescript
+ * const site = createSite({
+ *   $id: 'https://schema.org.ai/sites/docs',
+ *   name: 'Documentation',
+ *   description: 'Product documentation site',
+ *   url: 'https://docs.example.com',
+ *   siteType: 'docs'
+ * })
+ * ```
+ */
+export declare function createSite(input: Omit<Site, '$type' | 'status'> & {
+    status?: Site['status'];
+}): Site;
+/**
+ * Service - Backend service product
+ *
+ * Backend services with optional endpoints. Services are typically
+ * internal components that power applications and APIs.
+ *
+ * Unlike {@link API}, Service represents internal infrastructure
+ * rather than public programmatic interfaces.
+ *
+ * @see https://schema.org.ai/Service
+ *
+ * @example
+ * ```typescript
+ * const service = createService({
+ *   $id: 'https://schema.org.ai/services/auth',
+ *   name: 'Auth Service',
+ *   description: 'Authentication and authorization service',
+ *   endpoints: ['/login', '/logout', '/refresh']
+ * })
+ * // service.$type === 'https://schema.org.ai/Service'
+ * // service.status === 'active' (default)
+ * ```
+ */
+export interface Service {
+    /** Unique identifier URI (JSON-LD `@id` equivalent) */
+    $id: string;
+    /** Type URI (JSON-LD `@type` equivalent) */
+    $type: 'https://schema.org.ai/Service';
+    /** Human-readable name */
+    name: string;
+    /** Description of the service */
+    description: string;
+    /** Service status - defaults to 'active' when created via factory */
+    status: 'active' | 'inactive' | 'archived';
+    /** Optional list of endpoint paths this service exposes */
+    endpoints?: string[];
+}
+/**
+ * Zod schema for validating Service objects
+ *
+ * Use this schema for runtime validation of Service data.
+ *
+ * @see {@link Service}
+ * @see {@link isService}
+ *
+ * @example
+ * ```typescript
+ * const result = ServiceSchema.safeParse(data)
+ * if (result.success) {
+ *   console.log(result.data.name, result.data.endpoints)
+ * }
+ * ```
+ */
+export declare const ServiceSchema: z.ZodObject<{
+    $id: z.ZodString;
+    $type: z.ZodLiteral<"https://schema.org.ai/Service">;
+    name: z.ZodString;
+    description: z.ZodString;
+    status: z.ZodEnum<["active", "inactive", "archived"]>;
+    endpoints: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    $id: string;
+    $type: "https://schema.org.ai/Service";
+    status: "active" | "inactive" | "archived";
+    name: string;
+    description: string;
+    endpoints?: string[] | undefined;
+}, {
+    $id: string;
+    $type: "https://schema.org.ai/Service";
+    status: "active" | "inactive" | "archived";
+    name: string;
+    description: string;
+    endpoints?: string[] | undefined;
+}>;
+/**
+ * Type guard to check if an object is a valid Service
+ *
+ * Uses Zod schema validation under the hood.
+ *
+ * @param obj - Object to validate
+ * @returns True if valid Service (JSON-LD style with optional endpoints)
+ *
+ * @see {@link Service}
+ * @see {@link ServiceSchema}
+ *
+ * @example
+ * ```typescript
+ * if (isService(data)) {
+ *   // TypeScript knows data is Service here
+ *   console.log(data.name, data.endpoints)
+ * }
+ * ```
+ */
+export declare function isService(obj: unknown): obj is Service;
+/**
+ * Factory function to create a new Service
+ *
+ * Automatically sets `$type` to 'https://schema.org.ai/Service' and
+ * defaults `status` to 'active' if not provided.
+ *
+ * @param input - Service data (status defaults to 'active')
+ * @returns Complete Service with $type auto-filled
+ *
+ * @see {@link Service}
+ *
+ * @example
+ * ```typescript
+ * const service = createService({
+ *   $id: 'https://schema.org.ai/services/auth',
+ *   name: 'Auth Service',
+ *   description: 'Authentication service',
+ *   endpoints: ['/login', '/logout']
+ * })
+ * ```
+ */
+export declare function createService(input: Omit<Service, '$type' | 'status'> & {
+    status?: Service['status'];
+}): Service;
+/**
+ * Feature lifecycle status type
+ *
+ * Represents the lifecycle stage of a feature:
+ * - `draft` - Feature is being designed/developed (default)
+ * - `beta` - Feature is available for testing
+ * - `ga` - Feature is generally available (stable)
+ * - `deprecated` - Feature is being phased out
+ *
+ * @see {@link Feature}
+ */
+export type FeatureStatus = 'draft' | 'beta' | 'ga' | 'deprecated';
+/**
+ * Feature - Product feature with lifecycle status
+ *
+ * Individual features within a product. Features have their own
+ * lifecycle status independent of the parent product.
+ *
+ * @see https://schema.org.ai/Feature
+ *
+ * @example
+ * ```typescript
+ * const feature = createFeature({
+ *   $id: 'https://schema.org.ai/features/dark-mode',
+ *   name: 'Dark Mode',
+ *   description: 'Toggle dark theme',
+ *   productId: 'https://schema.org.ai/products/dashboard',
+ *   status: 'ga'
+ * })
+ * // feature.$type === 'https://schema.org.ai/Feature'
+ * ```
+ *
+ * @example Feature lifecycle progression
+ * ```typescript
+ * // Feature starts as draft
+ * const feature = createFeature({
+ *   $id: 'new-feature',
+ *   name: 'New Feature',
+ *   description: 'A new feature',
+ *   productId: 'my-product'
+ * })
+ * // feature.status === 'draft' (default)
+ *
+ * // Later, promote to beta, then ga, or deprecate
+ * ```
+ */
+export interface Feature {
+    /** Unique identifier URI (JSON-LD `@id` equivalent) */
+    $id: string;
+    /** Type URI (JSON-LD `@type` equivalent) */
+    $type: 'https://schema.org.ai/Feature';
+    /** Human-readable name */
+    name: string;
+    /** Description of the feature */
+    description: string;
+    /** Reference to parent product $id */
+    productId: string;
+    /** Feature lifecycle status - defaults to 'draft' when created via factory */
+    status: FeatureStatus;
+}
+/**
+ * Zod schema for validating Feature objects
+ *
+ * Use this schema for runtime validation of Feature data.
+ *
+ * @see {@link Feature}
+ * @see {@link isFeature}
+ *
+ * @example
+ * ```typescript
+ * const result = FeatureSchema.safeParse(data)
+ * if (result.success) {
+ *   console.log(result.data.name, result.data.status)
+ * }
+ * ```
+ */
+export declare const FeatureSchema: z.ZodObject<{
+    $id: z.ZodString;
+    $type: z.ZodLiteral<"https://schema.org.ai/Feature">;
+    name: z.ZodString;
+    description: z.ZodString;
+    productId: z.ZodString;
+    status: z.ZodEnum<["draft", "beta", "ga", "deprecated"]>;
+}, "strip", z.ZodTypeAny, {
+    $id: string;
+    $type: "https://schema.org.ai/Feature";
+    status: "draft" | "beta" | "ga" | "deprecated";
+    name: string;
+    description: string;
+    productId: string;
+}, {
+    $id: string;
+    $type: "https://schema.org.ai/Feature";
+    status: "draft" | "beta" | "ga" | "deprecated";
+    name: string;
+    description: string;
+    productId: string;
+}>;
+/**
+ * Type guard to check if an object is a valid Feature
+ *
+ * Uses Zod schema validation under the hood.
+ *
+ * @param obj - Object to validate
+ * @returns True if valid Feature (JSON-LD style with productId and lifecycle status)
+ *
+ * @see {@link Feature}
+ * @see {@link FeatureSchema}
+ *
+ * @example
+ * ```typescript
+ * if (isFeature(data)) {
+ *   // TypeScript knows data is Feature here
+ *   console.log(data.name, data.status, data.productId)
+ * }
+ * ```
+ */
+export declare function isFeature(obj: unknown): obj is Feature;
+/**
+ * Factory function to create a new Feature
+ *
+ * Automatically sets `$type` to 'https://schema.org.ai/Feature' and
+ * defaults `status` to 'draft' if not provided.
+ *
+ * @param input - Feature data (status defaults to 'draft')
+ * @returns Complete Feature with $type auto-filled
+ *
+ * @see {@link Feature}
+ * @see {@link FeatureStatus}
+ *
+ * @example
+ * ```typescript
+ * const feature = createFeature({
+ *   $id: 'https://schema.org.ai/features/dark-mode',
+ *   name: 'Dark Mode',
+ *   description: 'Toggle dark theme',
+ *   productId: 'https://schema.org.ai/products/dashboard'
+ * })
+ * // feature.status === 'draft' (default)
+ * ```
+ */
+export declare function createFeature(input: Omit<Feature, '$type' | 'status'> & {
+    status?: FeatureStatus;
+}): Feature;
+/**
+ * Base digital product definition for builder pattern
+ *
+ * Used by ProductBuilder and related fluent APIs.
+ * Uses `id` (without $ prefix) for builder ergonomics.
+ *
+ * @example
+ * ```typescript
+ * const product: DigitalProduct = {
+ *   id: 'my-product',
+ *   name: 'My Product',
+ *   description: 'A product',
+ *   version: '1.0.0'
+ * }
+ * ```
  */
 export interface DigitalProduct {
     /** Unique identifier for this product */
@@ -22,7 +808,11 @@ export interface DigitalProduct {
     status?: 'draft' | 'active' | 'deprecated';
 }
 /**
- * Application definition - interactive user-facing software
+ * Application definition for builder pattern
+ *
+ * Used by AppBuilder for fluent API definitions.
+ *
+ * @see {@link App} for JSON-LD compatible type
  */
 export interface AppDefinition extends DigitalProduct {
     type: 'app';
@@ -91,7 +881,11 @@ export interface AuthConfig {
     protectedRoutes?: string[];
 }
 /**
- * API definition - programmatic interface
+ * API definition for builder pattern
+ *
+ * Used by APIBuilder for fluent API definitions.
+ *
+ * @see {@link API} for JSON-LD compatible type
  */
 export interface APIDefinition extends DigitalProduct {
     type: 'api';
@@ -162,7 +956,9 @@ export interface RateLimitConfig {
     onExceeded?: 'reject' | 'queue' | 'custom';
 }
 /**
- * Content definition - text/media content
+ * Content definition for builder pattern
+ *
+ * Defines text/media content structure for the Content builder.
  */
 export interface ContentDefinition extends DigitalProduct {
     type: 'content';
@@ -200,7 +996,9 @@ export interface WorkflowDefinition {
     }[];
 }
 /**
- * Data definition - structured data/database
+ * Data definition for builder pattern
+ *
+ * Defines structured data/database schemas for the Data builder.
  */
 export interface DataDefinition extends DigitalProduct {
     type: 'data';
@@ -255,7 +1053,9 @@ export interface ValidationRule {
     message?: string;
 }
 /**
- * Dataset definition - curated data collection
+ * Dataset definition for builder pattern
+ *
+ * Defines curated data collection structure for the Dataset builder.
  */
 export interface DatasetDefinition extends DigitalProduct {
     type: 'dataset';
@@ -273,7 +1073,11 @@ export interface DatasetDefinition extends DigitalProduct {
     updateFrequency?: 'realtime' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'static';
 }
 /**
- * Site definition - website/documentation
+ * Site definition for builder pattern
+ *
+ * Used by SiteBuilder for fluent API definitions.
+ *
+ * @see {@link Site} for JSON-LD compatible type
  */
 export interface SiteDefinition extends DigitalProduct {
     type: 'site';
@@ -348,7 +1152,9 @@ export interface AnalyticsConfig {
     config?: Record<string, unknown>;
 }
 /**
- * MCP (Model Context Protocol) server definition
+ * MCP (Model Context Protocol) server definition for builder pattern
+ *
+ * Defines MCP server structure for the MCP builder.
  */
 export interface MCPDefinition extends DigitalProduct {
     type: 'mcp';
@@ -417,7 +1223,9 @@ export interface MCPConfig {
     };
 }
 /**
- * SDK (Software Development Kit) definition
+ * SDK (Software Development Kit) definition for builder pattern
+ *
+ * Defines SDK structure for the SDK builder.
  */
 export interface SDKDefinition extends DigitalProduct {
     type: 'sdk';
@@ -482,11 +1290,17 @@ export interface DeploymentTarget {
     env?: Record<string, string>;
 }
 /**
- * Union of all product types
+ * Union of all builder pattern product definition types
+ *
+ * Represents any product definition created through the builder API.
+ * For JSON-LD compatible types, use Product, App, API, Site, Service, Feature.
  */
 export type ProductDefinition = AppDefinition | APIDefinition | ContentDefinition | DataDefinition | DatasetDefinition | SiteDefinition | MCPDefinition | SDKDefinition;
 /**
  * Product builder - chainable API for creating products
+ *
+ * Provides a fluent interface for building ProductDefinition types.
+ * For simpler creation, use factory functions (createProduct, createApp, etc.).
  */
 export interface ProductBuilder<T extends ProductDefinition> {
     /** Set product ID */
@@ -508,6 +1322,9 @@ export interface ProductBuilder<T extends ProductDefinition> {
 }
 /**
  * Product registry for storing products
+ *
+ * Registry for managing legacy ProductDefinition types.
+ * Provides CRUD operations for products by ID.
  */
 export interface ProductRegistry {
     /** Register a product */
@@ -525,4 +1342,5 @@ export interface ProductRegistry {
     /** Clear all products */
     clear(): void;
 }
+export {};
 //# sourceMappingURL=types.d.ts.map