@contractspec/lib.contracts-spec 2.0.0

package/dist/serialization/index.js

@@ -0,0 +1,179 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+// src/serialization/serializers.ts
+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";
+}
+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: {}
+  };
+}
+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 } : undefined
+  };
+}
+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)
+  };
+}
+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 : undefined,
+      componentKey: spec.source.type === "component" ? spec.source.componentKey : undefined
+    },
+    targets: spec.targets
+  };
+}
+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
+  };
+}
+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
+  };
+}
+export {
+  serializeSchemaModel,
+  serializePresentationSpec,
+  serializeOperationSpec,
+  serializeFormSpec,
+  serializeEventSpec,
+  serializeDataViewSpec
+};

package/dist/serialization/serializers.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Serialization functions for converting spec types to their serialized forms.
+ */
+import type { AnySchemaModel } from '@contractspec/lib.schema';
+import type { ResourceRefDescriptor } from '../resources';
+import type { AnyOperationSpec } from '../operations';
+import type { AnyEventSpec } from '../events';
+import type { PresentationSpec } from '../presentations';
+import type { DataViewSpec } from '../data-views';
+import type { FormSpec } from '../forms';
+import type { SerializedSchemaModel, SerializedOperationSpec, SerializedEventSpec, SerializedPresentationSpec, SerializedDataViewSpec, SerializedFormSpec } from './types';
+/**
+ * Serialize a SchemaModel to a plain JSON object.
+ */
+export declare function serializeSchemaModel(model: AnySchemaModel | ResourceRefDescriptor<boolean> | null | undefined): SerializedSchemaModel | null;
+/**
+ * Serialize an OperationSpec to a plain JSON object.
+ */
+export declare function serializeOperationSpec(spec: AnyOperationSpec | null | undefined): SerializedOperationSpec | null;
+/**
+ * Serialize an EventSpec to a plain JSON object.
+ */
+export declare function serializeEventSpec(spec: AnyEventSpec | null | undefined): SerializedEventSpec | null;
+/**
+ * Serialize a PresentationSpec to a plain JSON object.
+ */
+export declare function serializePresentationSpec(spec: PresentationSpec | null | undefined): SerializedPresentationSpec | null;
+/**
+ * Serialize a DataViewSpec to a plain JSON object.
+ */
+export declare function serializeDataViewSpec(spec: DataViewSpec | null | undefined): SerializedDataViewSpec | null;
+/**
+ * Serialize a FormSpec to a plain JSON object.
+ */
+export declare function serializeFormSpec(spec: FormSpec | null | undefined): SerializedFormSpec | null;

package/dist/serialization/serializers.js

@@ -0,0 +1,180 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/serialization/serializers.ts
+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";
+}
+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: {}
+  };
+}
+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 } : undefined
+  };
+}
+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)
+  };
+}
+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 : undefined,
+      componentKey: spec.source.type === "component" ? spec.source.componentKey : undefined
+    },
+    targets: spec.targets
+  };
+}
+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
+  };
+}
+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
+  };
+}
+export {
+  serializeSchemaModel,
+  serializePresentationSpec,
+  serializeOperationSpec,
+  serializeFormSpec,
+  serializeEventSpec,
+  serializeDataViewSpec
+};

package/dist/serialization/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 */
+export interface SerializedSchemaModel {
+    name: string;
+    description?: string | null;
+    fields: Record<string, SerializedFieldConfig>;
+}
+export interface SerializedFieldConfig {
+    typeName: string;
+    isOptional: boolean;
+    isArray?: boolean;
+}
+/** Serialized operation spec for client components */
+export 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 */
+export interface SerializedEventSpec {
+    meta: {
+        key: string;
+        version: string;
+        stability?: string;
+        owners?: string[];
+        tags?: string[];
+        description?: string;
+    };
+    payload: SerializedSchemaModel | null;
+}
+/** Serialized presentation spec for client components */
+export 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 */
+export 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 */
+export 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;
+}

package/dist/serialization/types.js

@@ -0,0 +1 @@
+// @bun

package/dist/telemetry/anomaly.d.ts

@@ -0,0 +1,23 @@
+import type { TelemetryDispatch } from './tracker';
+import type { TelemetryAnomalyDetectionConfig } from './spec';
+export interface TelemetryAnomalyEvent {
+    dispatch: TelemetryDispatch;
+    threshold: TelemetryAnomalyDetectionConfig;
+    metric: string;
+    value: number | undefined;
+    type: 'min' | 'max';
+}
+export interface TelemetryAnomalyMonitorOptions {
+    onAnomaly?: (event: TelemetryAnomalyEvent) => void;
+    now?: () => Date;
+}
+export declare class TelemetryAnomalyMonitor {
+    private readonly onAnomaly?;
+    private readonly now;
+    private readonly samples;
+    constructor(options?: TelemetryAnomalyMonitorOptions);
+    observe(dispatch: TelemetryDispatch): void;
+    private extractMetric;
+    private emit;
+    reset(): void;
+}

package/dist/telemetry/anomaly.js

@@ -0,0 +1,91 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/telemetry/anomaly.ts
+class TelemetryAnomalyMonitor {
+  onAnomaly;
+  now;
+  samples = new Map;
+  constructor(options = {}) {
+    this.onAnomaly = options.onAnomaly;
+    this.now = options.now ?? (() => new Date);
+  }
+  observe(dispatch) {
+    const anomalyConfig = dispatch.definition.anomalyDetection;
+    if (!anomalyConfig?.enabled)
+      return;
+    if (!anomalyConfig.thresholds?.length)
+      return;
+    const eventKey = `${dispatch.name}.v${dispatch.version}`;
+    const count = this.samples.get(eventKey) ?? 0;
+    const newCount = count + 1;
+    this.samples.set(eventKey, newCount);
+    if (typeof anomalyConfig.minimumSample === "number" && newCount < anomalyConfig.minimumSample) {
+      return;
+    }
+    for (const threshold of anomalyConfig.thresholds) {
+      const value = this.extractMetric(dispatch, threshold.metric);
+      if (typeof value !== "number")
+        continue;
+      if (typeof threshold.min === "number" && value < threshold.min) {
+        this.emit(dispatch, anomalyConfig, threshold.metric, value, "min");
+      }
+      if (typeof threshold.max === "number" && value > threshold.max) {
+        this.emit(dispatch, anomalyConfig, threshold.metric, value, "max");
+      }
+    }
+  }
+  extractMetric(dispatch, metric) {
+    const value = dispatch.properties[metric];
+    if (typeof value === "number")
+      return value;
+    if (typeof value === "object" && value !== null && "value" in value) {
+      const maybeNumber = value.value;
+      return typeof maybeNumber === "number" ? maybeNumber : undefined;
+    }
+    return;
+  }
+  emit(dispatch, threshold, metric, value, type) {
+    this.onAnomaly?.({
+      dispatch,
+      threshold,
+      metric,
+      value,
+      type
+    });
+  }
+  reset() {
+    this.samples.clear();
+  }
+}
+export {
+  TelemetryAnomalyMonitor
+};

package/dist/telemetry/anomaly.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/telemetry/docs/telemetry.docblock.d.ts

@@ -0,0 +1,2 @@
+import type { DocBlock } from '@contractspec/lib.contracts-spec/docs';
+export declare const tech_contracts_telemetry_DocBlocks: DocBlock[];