digital-products 2.1.3 → 2.4.0

package/src/client.ts

@@ -0,0 +1,192 @@
+/**
+ * RPC Client for Digital Products
+ *
+ * Provides a typed RPC client that connects to the deployed
+ * digital-products worker using rpc.do for remote procedure calls.
+ *
+ * @example
+ * ```ts
+ * import { createDigitalProductsClient } from 'digital-products/client'
+ *
+ * const client = createDigitalProductsClient('https://digital-products.workers.dev')
+ * const product = await client.create({ name: 'My Product', description: 'A great product', version: '1.0.0' })
+ * const feature = await client.addFeature(product.id, { name: 'Search', description: 'Full-text search' })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { RPC, http } from 'rpc.do'
+
+// ==================== Types ====================
+
+interface ProductData {
+  id: string
+  name: string
+  description: string
+  version: string
+  status: 'draft' | 'active' | 'deprecated' | 'archived'
+  type?: string
+  features?: FeatureData[]
+  metadata?: Record<string, unknown>
+  tags?: string[]
+  createdAt: Date
+  updatedAt: Date
+}
+
+interface FeatureData {
+  id: string
+  name: string
+  description: string
+  status: 'draft' | 'beta' | 'ga' | 'deprecated'
+  productId: string
+  metadata?: Record<string, unknown>
+  createdAt: Date
+  updatedAt: Date
+}
+
+interface VersionData {
+  id: string
+  productId: string
+  version: string
+  changelog?: string
+  status: 'draft' | 'published' | 'deprecated'
+  features?: string[]
+  metadata?: Record<string, unknown>
+  createdAt: Date
+  publishedAt?: Date
+}
+
+interface BundleData {
+  id: string
+  name: string
+  description: string
+  productIds: string[]
+  pricing?: PricingData
+  metadata?: Record<string, unknown>
+  createdAt: Date
+  updatedAt: Date
+}
+
+interface PricingData {
+  model: 'free' | 'one-time' | 'subscription' | 'usage-based'
+  amount?: number
+  currency?: string
+  interval?: 'month' | 'year'
+}
+
+interface ListOptions {
+  limit?: number
+  offset?: number
+  status?: string
+  type?: string
+  orderBy?: string
+  order?: 'asc' | 'desc'
+}
+
+// ==================== API Type ====================
+
+/**
+ * DigitalProductsAPI - Type-safe interface matching ProductServiceCore RPC methods
+ *
+ * This interface mirrors all public methods on ProductServiceCore so that
+ * the RPC client provides full type safety when calling remote methods.
+ */
+export interface DigitalProductsAPI {
+  // Product CRUD
+  create(data: Partial<ProductData>): Promise<ProductData>
+  get(id: string): Promise<ProductData | null>
+  update(id: string, data: Partial<ProductData>): Promise<ProductData>
+  delete(id: string): Promise<boolean>
+  list(options?: ListOptions): Promise<ProductData[]>
+
+  // Feature Operations
+  addFeature(productId: string, featureData: Partial<FeatureData>): Promise<FeatureData>
+  updateFeature(featureId: string, data: Partial<FeatureData>): Promise<FeatureData>
+  removeFeature(featureId: string): Promise<boolean>
+  listFeatures(productId: string): Promise<FeatureData[]>
+
+  // Version Operations
+  publish(productId: string, versionStr: string, changelog?: string): Promise<VersionData>
+  listVersions(productId: string): Promise<VersionData[]>
+  getVersion(productId: string, versionStr: string): Promise<VersionData | null>
+  deprecateVersion(productId: string, versionStr: string): Promise<VersionData>
+
+  // Bundle Operations
+  compose(name: string, productIds: string[], options?: Partial<BundleData>): Promise<BundleData>
+  getBundle(bundleId: string): Promise<BundleData | null>
+  updateBundle(bundleId: string, data: Partial<BundleData>): Promise<BundleData>
+  listBundles(): Promise<BundleData[]>
+}
+
+// ==================== Client Options ====================
+
+/**
+ * Options for creating a digital products RPC client
+ */
+export interface DigitalProductsClientOptions {
+  /** Authentication token or API key */
+  token?: string
+  /** Request timeout in milliseconds */
+  timeout?: number
+  /** Custom headers to include in requests */
+  headers?: Record<string, string>
+}
+
+// ==================== Client Factory ====================
+
+/** Default URL for the digital-products worker */
+const DEFAULT_URL = 'https://digital-products.workers.dev'
+
+/**
+ * Create a typed RPC client for the digital-products worker
+ *
+ * @param url - The URL of the deployed digital-products worker
+ * @param options - Optional client configuration
+ * @returns A typed RPC client with all ProductServiceCore methods
+ *
+ * @example
+ * ```ts
+ * import { createDigitalProductsClient } from 'digital-products/client'
+ *
+ * // Connect to production
+ * const client = createDigitalProductsClient('https://digital-products.workers.dev')
+ *
+ * // Create a product
+ * const product = await client.create({
+ *   name: 'My API',
+ *   description: 'A powerful API service',
+ *   version: '1.0.0',
+ * })
+ *
+ * // Add features
+ * await client.addFeature(product.id, { name: 'Rate Limiting', description: 'API rate limiting' })
+ * await client.addFeature(product.id, { name: 'Analytics', description: 'Usage analytics' })
+ *
+ * // Publish a version
+ * await client.publish(product.id, '1.0.0', 'Initial release')
+ *
+ * // Create a bundle
+ * const bundle = await client.compose('Enterprise Bundle', [product.id, otherProduct.id])
+ * ```
+ */
+export function createDigitalProductsClient(
+  url: string = DEFAULT_URL,
+  options?: DigitalProductsClientOptions
+) {
+  return RPC<DigitalProductsAPI>(http(url, options?.token))
+}
+
+/**
+ * Default client instance connected to the production digital-products worker
+ *
+ * @example
+ * ```ts
+ * import client from 'digital-products/client'
+ *
+ * const product = await client.create({ name: 'My Product', description: 'Great', version: '1.0.0' })
+ * ```
+ */
+const client = createDigitalProductsClient()
+
+export default client

package/src/content.ts

@@ -44,14 +44,14 @@ export function Content(config: Omit<ContentDefinition, 'type'>): ContentDefinit
     description: config.description,
     version: config.version,
     format: config.format || 'markdown',
-    source: config.source,
-    schema: config.schema,
-    frontmatter: config.frontmatter,
-    categories: config.categories,
-    workflow: config.workflow,
-    metadata: config.metadata,
-    tags: config.tags,
     status: config.status || 'active',
+    ...(config.source !== undefined && { source: config.source }),
+    ...(config.schema !== undefined && { schema: config.schema }),
+    ...(config.frontmatter !== undefined && { frontmatter: config.frontmatter }),
+    ...(config.categories !== undefined && { categories: config.categories }),
+    ...(config.workflow !== undefined && { workflow: config.workflow }),
+    ...(config.metadata !== undefined && { metadata: config.metadata }),
+    ...(config.tags !== undefined && { tags: config.tags }),
   }
 
   return registerProduct(content)

package/src/data.ts

@@ -2,7 +2,12 @@
  * Data() - Define structured data
  */
 
-import type { DataDefinition, IndexDefinition, RelationshipDefinition, ValidationRule } from './types.js'
+import type {
+  DataDefinition,
+  IndexDefinition,
+  RelationshipDefinition,
+  ValidationRule,
+} from './types.js'
 import type { SimpleSchema } from 'ai-functions'
 import { registerProduct } from './product.js'
 
@@ -44,12 +49,12 @@ export function Data(config: Omit<DataDefinition, 'type'>): DataDefinition {
     version: config.version,
     schema: config.schema,
     provider: config.provider || 'fs',
-    indexes: config.indexes,
-    relationships: config.relationships,
-    validation: config.validation,
-    metadata: config.metadata,
-    tags: config.tags,
     status: config.status || 'active',
+    ...(config.indexes !== undefined && { indexes: config.indexes }),
+    ...(config.relationships !== undefined && { relationships: config.relationships }),
+    ...(config.validation !== undefined && { validation: config.validation }),
+    ...(config.metadata !== undefined && { metadata: config.metadata }),
+    ...(config.tags !== undefined && { tags: config.tags }),
   }
 
   return registerProduct(data)
@@ -124,6 +129,6 @@ export function Validate(
     field,
     rule,
     params: paramsOrMessage,
-    message,
+    ...(message !== undefined && { message }),
   }
 }

package/src/dataset.ts

@@ -40,13 +40,13 @@ export function Dataset(config: Omit<DatasetDefinition, 'type'>): DatasetDefinit
     version: config.version,
     format: config.format || 'json',
     schema: config.schema,
-    source: config.source,
-    size: config.size,
-    license: config.license,
     updateFrequency: config.updateFrequency || 'static',
-    metadata: config.metadata,
-    tags: config.tags,
     status: config.status || 'active',
+    ...(config.source !== undefined && { source: config.source }),
+    ...(config.size !== undefined && { size: config.size }),
+    ...(config.license !== undefined && { license: config.license }),
+    ...(config.metadata !== undefined && { metadata: config.metadata }),
+    ...(config.tags !== undefined && { tags: config.tags }),
   }
 
   return registerProduct(dataset)

package/src/index.ts

@@ -1,20 +1,115 @@
 /**
  * digital-products - Primitives for defining and building digital products
  *
- * This package provides primitives for defining digital products:
- * - Apps: Interactive user-facing applications
- * - APIs: Programmatic interfaces
- * - Content: Text/media content with schemas
- * - Data: Structured data definitions
- * - Datasets: Curated data collections
- * - Sites: Websites and documentation
- * - MCPs: Model Context Protocol servers
- * - SDKs: Software development kits
+ * This package provides primitives for defining digital products using JSON-LD
+ * style conventions with `$id` and `$type` fields for schema.org.ai compatibility.
+ *
+ * ## Product Types
+ *
+ * - {@link Product} - Base product interface
+ * - {@link App} - Interactive user-facing applications (web, mobile, desktop)
+ * - {@link API} - Programmatic interfaces with versioning and auth
+ * - {@link Site} - Websites (marketing, docs, blog)
+ * - {@link Service} - Backend services with endpoints
+ * - {@link Feature} - Product features with lifecycle status
+ *
+ * ## Validation & Type Guards
+ *
+ * Each product type includes:
+ * - Zod schema for runtime validation (e.g., {@link AppSchema})
+ * - Type guard function (e.g., {@link isApp})
+ * - Factory function with defaults (e.g., {@link createApp})
+ *
+ * ## Builder Pattern (Legacy)
+ *
+ * The `*Builder` functions and `*Definition` types are maintained for
+ * backwards compatibility. New code should use the unified JSON-LD types.
  *
  * @packageDocumentation
+ *
+ * @example Creating an App
+ * ```typescript
+ * import { createApp, isApp, AppSchema, App } from 'digital-products'
+ *
+ * // Using factory function (recommended)
+ * const app = createApp({
+ *   $id: 'https://schema.org.ai/apps/dashboard',
+ *   name: 'Dashboard',
+ *   description: 'Admin dashboard application',
+ *   platform: 'web',
+ *   url: 'https://dashboard.example.com'
+ * })
+ * // app.$type === 'https://schema.org.ai/App'
+ * // app.status === 'active' (default)
+ *
+ * // Type guard
+ * if (isApp(data)) {
+ *   console.log(data.platform) // TypeScript knows this is App
+ * }
+ *
+ * // Zod validation
+ * const result = AppSchema.safeParse(untrustedData)
+ * if (result.success) {
+ *   console.log(result.data.name)
+ * }
+ * ```
+ *
+ * @example Creating an API
+ * ```typescript
+ * import { createAPI, API, APISchema } from 'digital-products'
+ *
+ * const api = createAPI({
+ *   $id: 'https://schema.org.ai/apis/users',
+ *   name: 'Users API',
+ *   description: 'User management REST API',
+ *   baseUrl: 'https://api.example.com/v1',
+ *   version: '1.0.0',
+ *   authentication: 'bearer'
+ * })
+ * // api.$type === 'https://schema.org.ai/API'
+ * ```
+ *
+ * @example Creating a Site
+ * ```typescript
+ * import { createSite, Site, SiteSchema } from 'digital-products'
+ *
+ * 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 all types
+// =============================================================================
+// UNIFIED TYPES (JSON-LD Style) - Recommended
+// =============================================================================
+//
+// These exports from types.ts include:
+//
+// INTERFACES (JSON-LD style with $id/$type):
+//   - Product      - Base product interface
+//   - App          - Application (web, mobile, desktop)
+//   - API          - API with versioning and authentication
+//   - Site         - Website (marketing, docs, blog)
+//   - Service      - Backend service with endpoints
+//   - Feature      - Product feature with lifecycle
+//
+// ZOD SCHEMAS (runtime validation):
+//   - ProductSchema, AppSchema, APISchema, SiteSchema, ServiceSchema, FeatureSchema
+//
+// TYPE GUARDS:
+//   - isProduct, isApp, isAPI, isSite, isService, isFeature
+//
+// FACTORY FUNCTIONS (with sensible defaults):
+//   - createProduct, createApp, createAPI, createSite, createService, createFeature
+//
+// LEGACY TYPES (for backwards compatibility):
+//   - DigitalProduct, AppDefinition, APIDefinition, SiteDefinition, etc.
+//
 export * from './types.js'
 
 // Export entity definitions (Nouns) as namespace to avoid conflicts with types
@@ -43,13 +138,54 @@ export {
 // Export registry
 export { registry } from './registry.js'
 
-// Export product constructors
-export { Product, createProduct, registerProduct } from './product.js'
-export { App, Route, State, Auth } from './app.js'
-export { API, Endpoint, APIAuth, RateLimit } from './api.js'
+// =============================================================================
+// BUILDER PATTERN (Legacy API)
+// =============================================================================
+//
+// These builder functions create *Definition types (e.g., AppDefinition),
+// which use `id` and `type` fields instead of JSON-LD `$id`/`$type`.
+//
+// For new code, prefer the unified types above:
+//   - createApp()  creates App with $id/$type (JSON-LD)
+//   - AppBuilder() creates AppDefinition with id/type (legacy)
+//
+// The *Builder exports are renamed to avoid conflicts with the type interfaces.
+// The original function names (App, API, Site) are also exported for backwards
+// compatibility - TypeScript allows functions and types to share the same name.
+//
+
+/** @deprecated Use createProduct() from unified types instead */
+export {
+  Product as ProductBuilder,
+  createProduct as createProductDefinition,
+  registerProduct,
+} from './product.js'
+
+/** @deprecated Use createApp() from unified types instead */
+export { App as AppBuilder, Route, State, Auth } from './app.js'
+
+/** @deprecated Use createAPI() from unified types instead */
+export { API as APIBuilder, Endpoint, APIAuth, RateLimit } from './api.js'
+
 export { Content, Workflow } from './content.js'
 export { Data, Index, Relationship, Validate } from './data.js'
 export { Dataset } from './dataset.js'
-export { Site, Nav, SEO, Analytics } from './site.js'
+
+/** @deprecated Use createSite() from unified types instead */
+export { Site as SiteBuilder, Nav, SEO, Analytics } from './site.js'
+
 export { MCP, Tool, Resource, Prompt, MCPConfig } from './mcp.js'
 export { SDK, Export, Example } from './sdk.js'
+
+// Re-export builder functions under original names for backwards compatibility.
+// This allows: import { Site } from 'digital-products'; Site({...}) // builder
+// While also: import type { Site } from 'digital-products'; const x: Site = {...} // type
+// TypeScript allows function and type/interface with same name.
+import { Product as ProductFn } from './product.js'
+import { App as AppFn } from './app.js'
+import { API as APIFn } from './api.js'
+import { Site as SiteFn } from './site.js'
+
+// Export builder functions - these shadow the type exports at runtime
+// (which is fine since TypeScript types are erased at compile time)
+export { ProductFn as Product, AppFn as App, APIFn as API, SiteFn as Site }

package/src/mcp.ts

@@ -44,13 +44,13 @@ export function MCP(config: Omit<MCPDefinition, 'type'>): MCPDefinition {
     description: config.description,
     version: config.version,
     transport: config.transport,
-    tools: config.tools,
-    resources: config.resources,
-    prompts: config.prompts,
-    config: config.config,
-    metadata: config.metadata,
-    tags: config.tags,
     status: config.status || 'active',
+    ...(config.tools !== undefined && { tools: config.tools }),
+    ...(config.resources !== undefined && { resources: config.resources }),
+    ...(config.prompts !== undefined && { prompts: config.prompts }),
+    ...(config.config !== undefined && { config: config.config }),
+    ...(config.metadata !== undefined && { metadata: config.metadata }),
+    ...(config.tags !== undefined && { tags: config.tags }),
   }
 
   return registerProduct(mcp)
@@ -78,14 +78,14 @@ export function MCP(config: Omit<MCPDefinition, 'type'>): MCPDefinition {
 export function Tool(
   name: string,
   description: string,
-  inputSchema: SimpleSchema,
+  inputSchema: Record<string, unknown>,
   handler?: (input: unknown) => Promise<unknown>
 ): MCPTool {
   return {
     name,
     description,
-    inputSchema,
-    handler,
+    inputSchema: inputSchema as MCPTool['inputSchema'],
+    ...(handler !== undefined && { handler }),
   }
 }
 
@@ -112,7 +112,7 @@ export function Resource(
     uri,
     name,
     description,
-    mimeType,
+    ...(mimeType !== undefined && { mimeType }),
   }
 }
 
@@ -135,11 +135,18 @@ export function Prompt(
   template: string,
   args?: SimpleSchema
 ): MCPPrompt {
+  if (args !== undefined) {
+    return {
+      name,
+      description,
+      template,
+      arguments: args as Record<string, unknown>,
+    }
+  }
   return {
     name,
     description,
     template,
-    arguments: args,
   }
 }
 

package/src/product.ts

@@ -24,9 +24,9 @@ export function Product(config: Omit<DigitalProduct, 'type'>): DigitalProduct {
     name: config.name,
     description: config.description,
     version: config.version,
-    metadata: config.metadata,
-    tags: config.tags,
     status: config.status || 'active',
+    ...(config.metadata !== undefined && { metadata: config.metadata }),
+    ...(config.tags !== undefined && { tags: config.tags }),
   }
 
   return product

package/src/sdk.ts

@@ -62,14 +62,14 @@ export function SDK(config: Omit<SDKDefinition, 'type'>): SDKDefinition {
     description: config.description,
     version: config.version,
     language: config.language,
-    api: config.api,
-    exports: config.exports,
-    install: config.install,
-    docs: config.docs,
-    examples: config.examples,
-    metadata: config.metadata,
-    tags: config.tags,
     status: config.status || 'active',
+    ...(config.api !== undefined && { api: config.api }),
+    ...(config.exports !== undefined && { exports: config.exports }),
+    ...(config.install !== undefined && { install: config.install }),
+    ...(config.docs !== undefined && { docs: config.docs }),
+    ...(config.examples !== undefined && { examples: config.examples }),
+    ...(config.metadata !== undefined && { metadata: config.metadata }),
+    ...(config.tags !== undefined && { tags: config.tags }),
   }
 
   return registerProduct(sdk)
@@ -108,14 +108,53 @@ export function Export(
     methods?: SDKExport[]
   }
 ): SDKExport {
-  return {
-    type,
-    name,
-    description,
-    parameters: options?.parameters,
-    returns: options?.returns,
-    methods: options?.methods,
+  const base = { type, name, description }
+
+  // Build the result object conditionally to satisfy exactOptionalPropertyTypes
+  // Cast to Record<string, unknown> to match the local SimpleSchema type
+  if (
+    options?.parameters !== undefined &&
+    options?.returns !== undefined &&
+    options?.methods !== undefined
+  ) {
+    return {
+      ...base,
+      parameters: options.parameters as Record<string, unknown>,
+      returns: options.returns as Record<string, unknown>,
+      methods: options.methods,
+    }
+  }
+  if (options?.parameters !== undefined && options?.returns !== undefined) {
+    return {
+      ...base,
+      parameters: options.parameters as Record<string, unknown>,
+      returns: options.returns as Record<string, unknown>,
+    }
+  }
+  if (options?.parameters !== undefined && options?.methods !== undefined) {
+    return {
+      ...base,
+      parameters: options.parameters as Record<string, unknown>,
+      methods: options.methods,
+    }
+  }
+  if (options?.returns !== undefined && options?.methods !== undefined) {
+    return {
+      ...base,
+      returns: options.returns as Record<string, unknown>,
+      methods: options.methods,
+    }
+  }
+  if (options?.parameters !== undefined) {
+    return { ...base, parameters: options.parameters as Record<string, unknown> }
+  }
+  if (options?.returns !== undefined) {
+    return { ...base, returns: options.returns as Record<string, unknown> }
+  }
+  if (options?.methods !== undefined) {
+    return { ...base, methods: options.methods }
   }
+  return base
 }
 
 /**
@@ -143,6 +182,6 @@ export function Example(
     title,
     description,
     code,
-    output,
+    ...(output !== undefined && { output }),
   }
 }

package/src/site.ts

@@ -52,14 +52,14 @@ export function Site(config: Omit<SiteDefinition, 'type'>): SiteDefinition {
     description: config.description,
     version: config.version,
     generator: config.generator || 'next',
-    structure: config.structure,
-    navigation: config.navigation,
-    seo: config.seo,
-    analytics: config.analytics,
-    deployment: config.deployment,
-    metadata: config.metadata,
-    tags: config.tags,
     status: config.status || 'active',
+    ...(config.structure !== undefined && { structure: config.structure }),
+    ...(config.navigation !== undefined && { navigation: config.navigation }),
+    ...(config.seo !== undefined && { seo: config.seo }),
+    ...(config.analytics !== undefined && { analytics: config.analytics }),
+    ...(config.deployment !== undefined && { deployment: config.deployment }),
+    ...(config.metadata !== undefined && { metadata: config.metadata }),
+    ...(config.tags !== undefined && { tags: config.tags }),
   }
 
   return registerProduct(site)
@@ -123,5 +123,9 @@ export function Analytics(
   id: string,
   config?: Record<string, unknown>
 ): AnalyticsConfig {
-  return { provider, id, config }
+  return {
+    provider,
+    id,
+    ...(config !== undefined && { config }),
+  }
 }