@contractspec/lib.contracts 1.48.1 → 1.50.0

package/dist/ownership.d.ts

@@ -2,82 +2,207 @@ import { DocId } from "./docs/registry.js";
 import "./docs/index.js";
 
 //#region src/ownership.d.ts
+
+/**
+ * Lifecycle stability stages for specs.
+ *
+ * Specs progress through these stages as they mature:
+ * - `idea`: Initial concept, not implemented
+ * - `in_creation`: Currently being built
+ * - `experimental`: Working but may change significantly
+ * - `beta`: Feature-complete, seeking feedback
+ * - `stable`: Production-ready, breaking changes require major version bump
+ * - `deprecated`: Scheduled for removal, use alternatives
+ */
 declare const StabilityEnum: {
+  /** Initial concept, not yet implemented. */
   readonly Idea: "idea";
+  /** Currently being built, not ready for use. */
   readonly InCreation: "in_creation";
+  /** Working but unstable, may change significantly. */
   readonly Experimental: "experimental";
+  /** Feature-complete, seeking feedback before stabilization. */
   readonly Beta: "beta";
+  /** Production-ready, follows semantic versioning. */
   readonly Stable: "stable";
+  /** Scheduled for removal, use alternatives. */
   readonly Deprecated: "deprecated";
 };
+/** Stability level for a spec's lifecycle stage. */
 type Stability = (typeof StabilityEnum)[keyof typeof StabilityEnum];
+/**
+ * Curated owner identifiers for business/product ownership.
+ *
+ * Used for CODEOWNERS, on-call routing, and approval workflows.
+ * Custom owner strings are also allowed for flexibility.
+ */
 declare const OwnersEnum: {
+  /** Core platform team. */
   readonly PlatformCore: "platform.core";
+  /** Sigil/auth team. */
   readonly PlatformSigil: "platform.sigil";
+  /** Marketplace team. */
   readonly PlatformMarketplace: "platform.marketplace";
+  /** Messaging/notifications team. */
   readonly PlatformMessaging: "platform.messaging";
+  /** Content/CMS team. */
   readonly PlatformContent: "platform.content";
+  /** Feature flags team. */
   readonly PlatformFeatureFlags: "platform.featureflags";
+  /** Finance/billing team. */
   readonly PlatformFinance: "platform.finance";
 };
+/**
+ * Owner identifier for a spec.
+ * Can be a predefined OwnersEnum value or any custom string.
+ */
 type Owner = (typeof OwnersEnum)[keyof typeof OwnersEnum] | (string & {});
+/** @deprecated Use OwnersEnum instead. */
 declare const Owners: {
+  /** Core platform team. */
   readonly PlatformCore: "platform.core";
+  /** Sigil/auth team. */
   readonly PlatformSigil: "platform.sigil";
+  /** Marketplace team. */
   readonly PlatformMarketplace: "platform.marketplace";
+  /** Messaging/notifications team. */
   readonly PlatformMessaging: "platform.messaging";
+  /** Content/CMS team. */
   readonly PlatformContent: "platform.content";
+  /** Feature flags team. */
   readonly PlatformFeatureFlags: "platform.featureflags";
+  /** Finance/billing team. */
   readonly PlatformFinance: "platform.finance";
 };
+/**
+ * Common tags for categorizing specs.
+ *
+ * Used for search, grouping, and documentation navigation.
+ * Custom tag strings are also allowed for flexibility.
+ */
 declare const TagsEnum: {
+  /** Spots/locations domain. */
   readonly Spots: "spots";
+  /** Collectivity/community domain. */
   readonly Collectivity: "collectivity";
+  /** Marketplace domain. */
   readonly Marketplace: "marketplace";
+  /** Seller-related features. */
   readonly Sellers: "sellers";
+  /** Authentication features. */
   readonly Auth: "auth";
+  /** Login flows. */
   readonly Login: "login";
+  /** Signup flows. */
   readonly Signup: "signup";
+  /** Onboarding/guides. */
   readonly Guide: "guide";
+  /** Documentation. */
   readonly Docs: "docs";
+  /** Internationalization. */
   readonly I18n: "i18n";
+  /** Incident management. */
   readonly Incident: "incident";
+  /** Automation/workflows. */
   readonly Automation: "automation";
+  /** Code hygiene/maintenance. */
   readonly Hygiene: "hygiene";
 };
+/**
+ * Tag for categorizing a spec.
+ * Can be a predefined TagsEnum value or any custom string.
+ */
 type Tag = (typeof TagsEnum)[keyof typeof TagsEnum] | (string & {});
+/** @deprecated Use TagsEnum instead. */
 declare const Tags: {
+  /** Spots/locations domain. */
   readonly Spots: "spots";
+  /** Collectivity/community domain. */
   readonly Collectivity: "collectivity";
+  /** Marketplace domain. */
   readonly Marketplace: "marketplace";
+  /** Seller-related features. */
   readonly Sellers: "sellers";
+  /** Authentication features. */
   readonly Auth: "auth";
+  /** Login flows. */
   readonly Login: "login";
+  /** Signup flows. */
   readonly Signup: "signup";
+  /** Onboarding/guides. */
   readonly Guide: "guide";
+  /** Documentation. */
   readonly Docs: "docs";
+  /** Internationalization. */
   readonly I18n: "i18n";
+  /** Incident management. */
   readonly Incident: "incident";
+  /** Automation/workflows. */
   readonly Automation: "automation";
+  /** Code hygiene/maintenance. */
   readonly Hygiene: "hygiene";
 };
+/**
+ * Common metadata interface for all ContractSpec specifications.
+ *
+ * Every spec type (operations, events, presentations, etc.) extends this
+ * interface to provide consistent ownership, versioning, and discoverability.
+ *
+ * @example
+ * ```typescript
+ * const meta: OwnerShipMeta = {
+ *   key: 'auth.login',
+ *   version: '1.0.0',
+ *   description: 'Authenticates a user with email and password',
+ *   stability: StabilityEnum.Stable,
+ *   owners: [OwnersEnum.PlatformSigil],
+ *   tags: [TagsEnum.Auth, TagsEnum.Login],
+ * };
+ * ```
+ */
 interface OwnerShipMeta {
-  /** Breaking changes => bump version */
+  /**
+   * Semantic version string (e.g., "1.0.0").
+   * Bump for breaking changes according to semver rules.
+   */
   version: string;
-  /** Fully-qualified spec key (e.g., "sigil.beginSignup") */
+  /**
+   * Fully-qualified spec key (e.g., "sigil.beginSignup", "user.created").
+   * Must be unique within the spec type.
+   */
   key: string;
-  /** Human-friendly spec title (e.g., "Signup begin") */
+  /**
+   * Human-friendly title (e.g., "Begin Signup").
+   * Used in documentation and UI.
+   */
   title?: string;
-  /** Short human-friendly summary */
+  /**
+   * Short human-friendly summary of what this spec does.
+   * Should be concise (1-2 sentences).
+   */
   description: string;
+  /**
+   * Business domain this spec belongs to (e.g., "auth", "marketplace").
+   * Used for grouping and discovery.
+   */
   domain?: string;
-  /** Lifecycle marker for comms & tooling */
+  /**
+   * Lifecycle stability marker.
+   * Indicates maturity level and change expectations.
+   */
   stability: Stability;
-  /** Owners for CODEOWNERS / on-call / approvals */
+  /**
+   * Team/individual owners responsible for this spec.
+   * Used for CODEOWNERS, on-call routing, and approvals.
+   */
   owners: Owner[];
-  /** Search tags, grouping, docs navigation */
+  /**
+   * Tags for search, grouping, and documentation navigation.
+   */
   tags: Tag[];
-  /** Doc block(s) for this operation. */
+  /**
+   * Associated DocBlock identifiers for documentation linkage.
+   */
   docId?: DocId[];
 }
 //#endregion

package/dist/ownership.js

@@ -1,4 +1,15 @@
 //#region src/ownership.ts
+/**
+* Lifecycle stability stages for specs.
+*
+* Specs progress through these stages as they mature:
+* - `idea`: Initial concept, not implemented
+* - `in_creation`: Currently being built
+* - `experimental`: Working but may change significantly
+* - `beta`: Feature-complete, seeking feedback
+* - `stable`: Production-ready, breaking changes require major version bump
+* - `deprecated`: Scheduled for removal, use alternatives
+*/
 const StabilityEnum = {
 	Idea: "idea",
 	InCreation: "in_creation",
@@ -7,6 +18,12 @@ const StabilityEnum = {
 	Stable: "stable",
 	Deprecated: "deprecated"
 };
+/**
+* Curated owner identifiers for business/product ownership.
+*
+* Used for CODEOWNERS, on-call routing, and approval workflows.
+* Custom owner strings are also allowed for flexibility.
+*/
 const OwnersEnum = {
 	PlatformCore: "platform.core",
 	PlatformSigil: "platform.sigil",
@@ -16,7 +33,14 @@ const OwnersEnum = {
 	PlatformFeatureFlags: "platform.featureflags",
 	PlatformFinance: "platform.finance"
 };
+/** @deprecated Use OwnersEnum instead. */
 const Owners = OwnersEnum;
+/**
+* Common tags for categorizing specs.
+*
+* Used for search, grouping, and documentation navigation.
+* Custom tag strings are also allowed for flexibility.
+*/
 const TagsEnum = {
 	Spots: "spots",
 	Collectivity: "collectivity",
@@ -32,6 +56,7 @@ const TagsEnum = {
 	Automation: "automation",
 	Hygiene: "hygiene"
 };
+/** @deprecated Use TagsEnum instead. */
 const Tags = TagsEnum;
 
 //#endregion

package/dist/policy/spec.d.ts

@@ -1,6 +1,8 @@
 import { OwnerShipMeta } from "../ownership.js";
+import { VersionedSpecRef } from "../versioning/refs.js";
 
 //#region src/policy/spec.d.ts
+/** Effect of a policy rule: allow or deny access. */
 type PolicyEffect = 'allow' | 'deny';
 interface RelationshipDefinition {
   subjectType: string;
@@ -95,9 +97,10 @@ interface PolicySpec {
   rateLimits?: RateLimitDefinition[];
   opa?: PolicyOPAConfig;
 }
-interface PolicyRef {
-  key: string;
-  version: string;
-}
+/**
+ * Reference to a policy spec.
+ * Uses key and version to identify a specific policy.
+ */
+type PolicyRef = VersionedSpecRef;
 //#endregion
 export { AttributeMatcher, ConsentDefinition, FieldPolicyRule, PIIPolicy, PolicyCondition, PolicyEffect, PolicyMeta, PolicyOPAConfig, PolicyRef, PolicyRule, PolicySpec, RateLimitDefinition, RelationshipDefinition, RelationshipMatcher, ResourceMatcher, SubjectMatcher };

package/dist/serialization/index.d.ts

@@ -0,0 +1,3 @@
+import { SerializedDataViewSpec, SerializedEventSpec, SerializedFieldConfig, SerializedFormSpec, SerializedOperationSpec, SerializedPresentationSpec, SerializedSchemaModel } from "./types.js";
+import { serializeDataViewSpec, serializeEventSpec, serializeFormSpec, serializeOperationSpec, serializePresentationSpec, serializeSchemaModel } from "./serializers.js";
+export { SerializedDataViewSpec, SerializedEventSpec, SerializedFieldConfig, SerializedFormSpec, SerializedOperationSpec, SerializedPresentationSpec, SerializedSchemaModel, serializeDataViewSpec, serializeEventSpec, serializeFormSpec, serializeOperationSpec, serializePresentationSpec, serializeSchemaModel };

package/dist/serialization/index.js

@@ -0,0 +1,3 @@
+import { serializeDataViewSpec, serializeEventSpec, serializeFormSpec, serializeOperationSpec, serializePresentationSpec, serializeSchemaModel } from "./serializers.js";
+
+export { serializeDataViewSpec, serializeEventSpec, serializeFormSpec, serializeOperationSpec, serializePresentationSpec, serializeSchemaModel };

package/dist/serialization/serializers.d.ts

@@ -0,0 +1,40 @@
+import { PresentationSpec } from "../presentations/presentations.js";
+import { ResourceRefDescriptor } from "../resources.js";
+import { AnyOperationSpec } from "../operations/operation.js";
+import "../operations/index.js";
+import "../presentations/index.js";
+import { DataViewSpec } from "../data-views/spec.js";
+import "../data-views/index.js";
+import { AnyEventSpec } from "../events.js";
+import { FormSpec } from "../forms/forms.js";
+import "../forms/index.js";
+import { SerializedDataViewSpec, SerializedEventSpec, SerializedFormSpec, SerializedOperationSpec, SerializedPresentationSpec, SerializedSchemaModel } from "./types.js";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+
+//#region src/serialization/serializers.d.ts
+/**
+ * Serialize a SchemaModel to a plain JSON object.
+ */
+declare function serializeSchemaModel(model: AnySchemaModel | ResourceRefDescriptor<boolean> | null | undefined): SerializedSchemaModel | null;
+/**
+ * Serialize an OperationSpec to a plain JSON object.
+ */
+declare function serializeOperationSpec(spec: AnyOperationSpec | null | undefined): SerializedOperationSpec | null;
+/**
+ * Serialize an EventSpec to a plain JSON object.
+ */
+declare function serializeEventSpec(spec: AnyEventSpec | null | undefined): SerializedEventSpec | null;
+/**
+ * Serialize a PresentationSpec to a plain JSON object.
+ */
+declare function serializePresentationSpec(spec: PresentationSpec | null | undefined): SerializedPresentationSpec | null;
+/**
+ * Serialize a DataViewSpec to a plain JSON object.
+ */
+declare function serializeDataViewSpec(spec: DataViewSpec | null | undefined): SerializedDataViewSpec | null;
+/**
+ * Serialize a FormSpec to a plain JSON object.
+ */
+declare function serializeFormSpec(spec: FormSpec | null | undefined): SerializedFormSpec | null;
+//#endregion
+export { serializeDataViewSpec, serializeEventSpec, serializeFormSpec, serializeOperationSpec, serializePresentationSpec, serializeSchemaModel };

package/dist/serialization/serializers.js

@@ -0,0 +1,148 @@
+//#region src/serialization/serializers.ts
+/**
+* Type guard to check if a value is a ResourceRefDescriptor.
+*/
+function isResourceRefDescriptor(value) {
+	return typeof value === "object" && value !== null && "kind" in value && value.kind === "resource_ref";
+}
+function getTypeName(type) {
+	if (!type) return "unknown";
+	if (typeof type === "string") return type;
+	if (typeof type === "object") {
+		if ("config" in type && type.config?.name) return type.config.name;
+		if ("name" in type && typeof type.name === "string") return type.name;
+	}
+	return "unknown";
+}
+/**
+* Serialize a SchemaModel to a plain JSON object.
+*/
+function serializeSchemaModel(model) {
+	if (!model) return null;
+	if (isResourceRefDescriptor(model)) return {
+		name: `ResourceRef<${model.graphQLType}>`,
+		description: `Reference to ${model.graphQLType} resource (${model.uriTemplate})`,
+		fields: {}
+	};
+	if ("config" in model && model.config) {
+		const config = model.config;
+		return {
+			name: config.name,
+			description: config.description,
+			fields: Object.fromEntries(Object.entries(config.fields).map(([key, field]) => [key, {
+				typeName: getTypeName(field.type),
+				isOptional: field.isOptional,
+				isArray: field.isArray
+			}]))
+		};
+	}
+	return {
+		name: "unknown",
+		fields: {}
+	};
+}
+/**
+* Serialize an OperationSpec to a plain JSON object.
+*/
+function serializeOperationSpec(spec) {
+	if (!spec) return null;
+	return {
+		meta: {
+			key: spec.meta.key,
+			version: spec.meta.version,
+			stability: spec.meta.stability,
+			owners: spec.meta.owners,
+			tags: spec.meta.tags,
+			description: spec.meta.description,
+			goal: spec.meta.goal,
+			context: spec.meta.context
+		},
+		io: {
+			input: serializeSchemaModel(spec.io.input),
+			output: serializeSchemaModel(spec.io.output)
+		},
+		policy: spec.policy ? { auth: spec.policy.auth } : void 0
+	};
+}
+/**
+* Serialize an EventSpec to a plain JSON object.
+*/
+function serializeEventSpec(spec) {
+	if (!spec) return null;
+	return {
+		meta: {
+			key: spec.meta.key,
+			version: spec.meta.version,
+			stability: spec.meta.stability,
+			owners: spec.meta.owners,
+			tags: spec.meta.tags,
+			description: spec.meta.description
+		},
+		payload: serializeSchemaModel(spec.payload)
+	};
+}
+/**
+* Serialize a PresentationSpec to a plain JSON object.
+*/
+function serializePresentationSpec(spec) {
+	if (!spec) return null;
+	return {
+		meta: {
+			key: spec.meta.key,
+			version: spec.meta.version,
+			stability: spec.meta.stability,
+			owners: spec.meta.owners,
+			tags: spec.meta.tags,
+			description: spec.meta.description,
+			goal: spec.meta.goal,
+			context: spec.meta.context
+		},
+		source: {
+			type: spec.source.type,
+			framework: spec.source.type === "component" ? spec.source.framework : void 0,
+			componentKey: spec.source.type === "component" ? spec.source.componentKey : void 0
+		},
+		targets: spec.targets
+	};
+}
+/**
+* Serialize a DataViewSpec to a plain JSON object.
+*/
+function serializeDataViewSpec(spec) {
+	if (!spec) return null;
+	return {
+		meta: {
+			key: spec.meta.key,
+			version: spec.meta.version,
+			stability: spec.meta.stability,
+			owners: spec.meta.owners,
+			tags: spec.meta.tags,
+			description: spec.meta.description,
+			title: spec.meta.title
+		},
+		source: spec.source,
+		view: spec.view
+	};
+}
+/**
+* Serialize a FormSpec to a plain JSON object.
+*/
+function serializeFormSpec(spec) {
+	if (!spec) return null;
+	return {
+		meta: {
+			key: spec.meta.key,
+			version: spec.meta.version,
+			stability: spec.meta.stability,
+			owners: spec.meta.owners,
+			tags: spec.meta.tags,
+			description: spec.meta.description,
+			title: spec.meta.title
+		},
+		fields: spec.fields,
+		actions: spec.actions
+	};
+}
+
+//#endregion
+export { serializeDataViewSpec, serializeEventSpec, serializeFormSpec, serializeOperationSpec, serializePresentationSpec, serializeSchemaModel };

package/dist/serialization/types.d.ts

@@ -0,0 +1,103 @@
+//#region src/serialization/types.d.ts
+/**
+ * Serialized types for Server -> Client Component transfer.
+ *
+ * These are plain JSON-serializable versions of spec types that can be
+ * safely passed from Server Components to Client Components in Next.js.
+ */
+/** Serialized schema model that can be passed to client components */
+interface SerializedSchemaModel {
+  name: string;
+  description?: string | null;
+  fields: Record<string, SerializedFieldConfig>;
+}
+interface SerializedFieldConfig {
+  typeName: string;
+  isOptional: boolean;
+  isArray?: boolean;
+}
+/** Serialized operation spec for client components */
+interface SerializedOperationSpec {
+  meta: {
+    key: string;
+    version: string;
+    stability?: string;
+    owners?: string[];
+    tags?: string[];
+    description?: string;
+    goal?: string;
+    context?: string;
+  };
+  io: {
+    input: SerializedSchemaModel | null;
+    output: SerializedSchemaModel | null;
+  };
+  policy?: {
+    auth?: string;
+  };
+}
+/** Serialized event spec for client components */
+interface SerializedEventSpec {
+  meta: {
+    key: string;
+    version: string;
+    stability?: string;
+    owners?: string[];
+    tags?: string[];
+    description?: string;
+  };
+  payload: SerializedSchemaModel | null;
+}
+/** Serialized presentation spec for client components */
+interface SerializedPresentationSpec {
+  meta: {
+    key: string;
+    version: string;
+    stability?: string;
+    owners?: string[];
+    tags?: string[];
+    description?: string;
+    goal?: string;
+    context?: string;
+  };
+  source: {
+    type: string;
+    framework?: string;
+    componentKey?: string;
+  };
+  targets?: string[];
+}
+/** Serialized data view spec for client components */
+interface SerializedDataViewSpec {
+  meta: {
+    key: string;
+    version: string;
+    stability?: string;
+    owners?: string[];
+    tags?: string[];
+    description?: string;
+    title?: string;
+  };
+  /** Serialized source configuration */
+  source?: unknown;
+  /** Serialized view configuration */
+  view?: unknown;
+}
+/** Serialized form spec for client components */
+interface SerializedFormSpec {
+  meta: {
+    key: string;
+    version?: string;
+    stability?: string;
+    owners?: string[];
+    tags?: string[];
+    description?: string;
+    title?: string;
+  };
+  /** Serialized form fields (passed through for display) */
+  fields?: unknown;
+  /** Serialized form actions (passed through for display) */
+  actions?: unknown;
+}
+//#endregion
+export { SerializedDataViewSpec, SerializedEventSpec, SerializedFieldConfig, SerializedFormSpec, SerializedOperationSpec, SerializedPresentationSpec, SerializedSchemaModel };

package/dist/tests/spec.d.ts

@@ -1,14 +1,18 @@
 import { OwnerShipMeta } from "../ownership.js";
+import { OptionalVersionedSpecRef } from "../versioning/refs.js";
 
 //#region src/tests/spec.d.ts
-interface OperationTargetRef {
-  key: string;
-  version?: string;
-}
-interface WorkflowTargetRef {
-  key: string;
-  version?: string;
-}
+
+/**
+ * Reference to an operation to be tested.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type OperationTargetRef = OptionalVersionedSpecRef;
+/**
+ * Reference to a workflow to be tested.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type WorkflowTargetRef = OptionalVersionedSpecRef;
 type TestTarget = {
   type: 'operation';
   operation: OperationTargetRef;
@@ -66,10 +70,11 @@ interface TestSpec {
   scenarios: TestScenario[];
   coverage?: CoverageRequirement;
 }
-interface TestSpecRef {
-  key: string;
-  version?: string;
-}
+/**
+ * Reference to a test spec.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type TestSpecRef = OptionalVersionedSpecRef;
 declare class TestRegistry {
   private readonly items;
   register(spec: TestSpec): this;

package/dist/themes.d.ts

@@ -1,7 +1,9 @@
 import { OwnerShipMeta } from "./ownership.js";
+import { VersionedSpecRef } from "./versioning/refs.js";
 import { SpecContractRegistry } from "./registry.js";
 
 //#region src/themes.d.ts
+/** Scope at which a theme can be applied. */
 type ThemeScope = 'global' | 'tenant' | 'user';
 interface ThemeToken<T> {
   value: T;
@@ -39,10 +41,11 @@ interface ThemeSpec {
   components?: ComponentVariantSpec[];
   overrides?: ThemeOverride[];
 }
-interface ThemeRef {
-  key: string;
-  version: string;
-}
+/**
+ * Reference to a theme spec.
+ * Uses key and version to identify a specific theme.
+ */
+type ThemeRef = VersionedSpecRef;
 declare class ThemeRegistry extends SpecContractRegistry<'theme', ThemeSpec> {
   constructor(items?: ThemeSpec[]);
 }