@contractspec/bundle.library 0.0.0-canary-20260206014742

package/src/features/index.ts

@@ -0,0 +1,71 @@
+// Features
+export * from './docs';
+export { DocsFeature } from './docs.feature';
+export { MCPFeature } from './mcp.feature';
+export { PresentationsFeature } from './presentations.feature';
+
+// Feature Registry
+export {
+  createContractSpecFeatureRegistry,
+  getContractSpecFeatureRegistry,
+  resetContractSpecFeatureRegistry,
+} from './registry';
+
+// Contracts Registry (for resolving OpRef/EventRef/PresentationRef to full specs)
+export {
+  // Operations
+  createContractSpecOperationRegistry,
+  getContractSpecOperationRegistry,
+  resetContractSpecOperationRegistry,
+  resolveOperationSpec,
+  // Events
+  createContractSpecEventRegistry,
+  getContractSpecEventRegistry,
+  resetContractSpecEventRegistry,
+  resolveEventSpec,
+  // Presentations
+  createContractSpecPresentationRegistry,
+  getContractSpecPresentationRegistry,
+  resetContractSpecPresentationRegistry,
+  resolvePresentationSpec,
+  // DataViews
+  createContractSpecDataViewRegistry,
+  getContractSpecDataViewRegistry,
+  resetContractSpecDataViewRegistry,
+  resolveDataViewSpec,
+  // Forms
+  createContractSpecFormRegistry,
+  getContractSpecFormRegistry,
+  resetContractSpecFormRegistry,
+  resolveFormSpec,
+  // Serialized spec resolution (for Server -> Client Component transfer)
+  resolveSerializedOperationSpec,
+  resolveSerializedEventSpec,
+  resolveSerializedPresentationSpec,
+  resolveSerializedDataViewSpec,
+  resolveSerializedFormSpec,
+  // Reset all
+  resetAllContractSpecRegistries,
+} from './contracts-registry';
+
+// Serialized spec types for client components
+export type {
+  SerializedOperationSpec,
+  SerializedEventSpec,
+  SerializedPresentationSpec,
+  SerializedDataViewSpec,
+  SerializedFormSpec,
+  SerializedSchemaModel,
+} from './contracts-registry';
+
+// Re-export types and utilities from lib.contracts
+export type {
+  FeatureModuleSpec,
+  FeatureModuleMeta,
+  OpRef,
+  EventRef,
+  PresentationRef,
+  FeatureRef,
+} from '@contractspec/lib.contracts/features';
+
+export { FeatureRegistry } from '@contractspec/lib.contracts/features';

package/src/features/mcp.feature.ts

@@ -0,0 +1,32 @@
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';
+
+/**
+ * MCP (Model Context Protocol) integration feature for ContractSpec.
+ * Enables AI agent integration through MCP tools, resources, and prompts.
+ */
+export const MCPFeature: FeatureModuleSpec = {
+  meta: {
+    key: 'contractspec.mcp',
+    version: '1.0.0',
+    title: 'MCP Integration',
+    description: 'Model Context Protocol server for AI agent integration',
+    domain: 'platform',
+    owners: ['@platform.mcp'],
+    tags: ['mcp', 'ai-agents', 'tooling'],
+    stability: 'beta',
+  },
+  operations: [
+    { key: 'mcp.tool.register', version: '1.0.0' },
+    { key: 'mcp.resource.register', version: '1.0.0' },
+    { key: 'mcp.prompt.register', version: '1.0.0' },
+  ],
+  events: [
+    { key: 'mcp.tool_invoked', version: '1.0.0' },
+    { key: 'mcp.resource_accessed', version: '1.0.0' },
+  ],
+  presentations: [],
+  capabilities: {
+    provides: [{ key: 'contracts.mcp', version: '1.0.0' }],
+    requires: [{ key: 'contracts.operations', version: '1.0.0' }],
+  },
+};

package/src/features/presentations.feature.ts

@@ -0,0 +1,35 @@
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';
+
+/**
+ * Presentations feature for ContractSpec.
+ * Provides cross-platform rendering of contract-driven UI.
+ */
+export const PresentationsFeature: FeatureModuleSpec = {
+  meta: {
+    key: 'contractspec.presentations',
+    version: '1.0.0',
+    title: 'Presentation Runtime',
+    description: 'Cross-platform rendering of contract-driven UI',
+    domain: 'platform',
+    owners: ['@platform.presentations'],
+    tags: ['presentations', 'ui', 'rendering', 'cross-platform'],
+    stability: 'beta',
+  },
+  operations: [
+    { key: 'presentation.render', version: '1.0.0' },
+    { key: 'presentation.transform', version: '1.0.0' },
+  ],
+  events: [
+    { key: 'presentation.rendered', version: '1.0.0' },
+    { key: 'presentation.transformed', version: '1.0.0' },
+  ],
+  presentations: [
+    { key: 'form.standard', version: '1.0.0' },
+    { key: 'list.standard', version: '1.0.0' },
+    { key: 'detail.standard', version: '1.0.0' },
+  ],
+  capabilities: {
+    provides: [{ key: 'contracts.presentations', version: '1.0.0' }],
+    requires: [],
+  },
+};

package/src/features/registry.ts

@@ -0,0 +1,44 @@
+import { FeatureRegistry } from '@contractspec/lib.contracts/features';
+import { AppConfigFeature } from '@contractspec/lib.contracts/app-config';
+import { DocsFeature } from './docs.feature';
+import { MCPFeature } from './mcp.feature';
+import { PresentationsFeature } from './presentations.feature';
+
+/**
+ * Create and initialize the ContractSpec feature registry.
+ * Registers all ContractSpec features without validation (ops/presentations not registered).
+ */
+export function createContractSpecFeatureRegistry(): FeatureRegistry {
+  const features = new FeatureRegistry();
+
+  // Register ContractSpec-specific features
+  features.register(DocsFeature);
+  features.register(MCPFeature);
+  features.register(PresentationsFeature);
+
+  // Register lib.contracts features
+  features.register(AppConfigFeature);
+
+  return features;
+}
+
+/** Singleton instance of the feature registry. */
+let registryInstance: FeatureRegistry | null = null;
+
+/**
+ * Get the singleton ContractSpec feature registry.
+ * Creates the registry on first call, returns cached instance thereafter.
+ */
+export function getContractSpecFeatureRegistry(): FeatureRegistry {
+  if (!registryInstance) {
+    registryInstance = createContractSpecFeatureRegistry();
+  }
+  return registryInstance;
+}
+
+/**
+ * Reset the feature registry singleton (for testing).
+ */
+export function resetContractSpecFeatureRegistry(): void {
+  registryInstance = null;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './components/integrations';
+export * from './components/shared';
+export * from './components/shell';
+export * from './components/templates';
+export * from './components/docs';
+export * from './components/legal';
+
+// App config and features
+export * from './config';
+export * from './features';

package/src/infrastructure/elysia/index.ts

@@ -0,0 +1 @@
+export * from './logger';

package/src/infrastructure/elysia/logger.ts

@@ -0,0 +1,38 @@
+import { Logger, LogLevel } from '@contractspec/lib.logger';
+
+// Centralized logger configuration for the API
+export const createAppLogger = () =>
+  new Logger({
+    level:
+      process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG,
+    environment: process.env.NODE_ENV || 'development',
+    enableTracing: true,
+    enableTiming: true,
+    enableContext: true,
+    enableColors: process.env.NODE_ENV !== 'production',
+  });
+
+// Default logger instance for the application
+export const appLogger = createAppLogger();
+
+// Logger specifically for database operations
+export const dbLogger = new Logger({
+  level: process.env.NODE_ENV === 'production' ? LogLevel.WARN : LogLevel.DEBUG,
+  environment: process.env.NODE_ENV || 'development',
+  enableTracing: true,
+  enableTiming: true,
+  enableContext: true,
+  enableColors: process.env.NODE_ENV !== 'production',
+});
+
+// Logger for authentication operations
+export const authLogger = new Logger({
+  level: LogLevel.INFO, // Always log auth events
+  environment: process.env.NODE_ENV || 'development',
+  enableTracing: true,
+  enableTiming: true,
+  enableContext: true,
+  enableColors: process.env.NODE_ENV !== 'production',
+});
+
+export { Logger, LogLevel };

package/src/infrastructure/index.ts

@@ -0,0 +1 @@
+export * from './elysia';

package/src/libs/email/client.test.ts

@@ -0,0 +1,107 @@
+'use server';
+
+/* eslint-disable @typescript-eslint/no-non-null-assertion -- Pragmatic use of non-null assertion for tests */
+import { beforeEach, describe, expect, it } from 'bun:test';
+import { __internal, getEmailConfig, sendEmail } from './client';
+
+const ENV_KEYS = [
+  'SCALEWAY_ACCESS_KEY',
+  'SCALEWAY_SECRET_KEY',
+  'SCALEWAY_PROJECT_ID',
+  'SCALEWAY_ACCESS_KEY_QUEUE',
+  'SCALEWAY_SECRET_KEY_QUEUE',
+  'SCALEWAY_REGION',
+  'SCALEWAY_EMAIL_FROM_EMAIL',
+  'SCALEWAY_EMAIL_FROM_NAME',
+  'SCALEWAY_EMAIL_TEAM_EMAIL',
+  'SCALEWAY_EMAIL_TEAM_NAME',
+];
+
+const clearEnv = () => {
+  ENV_KEYS.forEach((key) => {
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Pragmatic use for environment cleanup in tests
+    delete process.env[key];
+  });
+};
+
+const setEnv = (values: Partial<Record<string, string>>) => {
+  Object.entries(values).forEach(([key, value]) => {
+    process.env[key] = value;
+  });
+};
+
+describe('email client config', () => {
+  beforeEach(() => {
+    __internal.resetCaches();
+    clearEnv();
+  });
+
+  it('returns a failure result when credentials are missing', () => {
+    const result = getEmailConfig();
+    expect(result.ok).toBeFalse();
+    expect(result.config).toBeUndefined();
+  });
+
+  it('prefers Scaleway env variables for config and region mapping', () => {
+    setEnv({
+      SCALEWAY_ACCESS_KEY: 'access',
+      SCALEWAY_SECRET_KEY: 'secret',
+      SCALEWAY_PROJECT_ID: 'project-123',
+      SCALEWAY_EMAIL_FROM_EMAIL: 'from@example.com',
+      SCALEWAY_EMAIL_FROM_NAME: 'From Name',
+      SCALEWAY_EMAIL_TEAM_EMAIL: 'team@example.com',
+      SCALEWAY_EMAIL_TEAM_NAME: 'Team Name',
+    });
+
+    const result = getEmailConfig();
+    expect(result.ok).toBeTrue();
+    expect(result.config?.accessKey).toBe('access');
+    expect(result.config?.secretKey).toBe('secret');
+    expect(result.config?.projectId).toBe('project-123');
+    expect(result.config?.region).toBe('fr-par');
+    expect(result.config?.from.email).toBe('from@example.com');
+    expect(result.config?.from.name).toBe('From Name');
+    expect(result.config?.teamInbox.email).toBe('team@example.com');
+    expect(result.config?.teamInbox.name).toBe('Team Name');
+  });
+
+  it('uses provided API factory to send email with reply-to header', async () => {
+    setEnv({
+      SCALEWAY_ACCESS_KEY: 'access',
+      SCALEWAY_SECRET_KEY: 'secret',
+      SCALEWAY_PROJECT_ID: 'project-123',
+    });
+
+    let captured: unknown = null;
+
+    __internal.setClient({
+      async createEmail(request: unknown) {
+        captured = request;
+        return { emails: [] };
+      },
+    });
+
+    const config = getEmailConfig().config!;
+
+    const response = await sendEmail(config, {
+      to: [{ email: 'user@example.com' }],
+      subject: 'Subject',
+      text: 'Plain text',
+      html: '<p>html</p>',
+      replyTo: 'reply@example.com',
+      context: 'test',
+    });
+
+    expect(response.success).toBeTrue();
+    const createEmailRequest = captured as Record<string, unknown>;
+    expect(createEmailRequest.region).toBe(config.region);
+    expect(createEmailRequest.projectId).toBe(config.projectId);
+    expect(createEmailRequest.from).toStrictEqual(config.from);
+    expect(createEmailRequest.to).toStrictEqual([
+      { email: 'user@example.com' },
+    ]);
+    expect(createEmailRequest.additionalHeaders).toStrictEqual([
+      { key: 'Reply-To', value: 'reply@example.com' },
+    ]);
+  });
+});

package/src/libs/email/client.ts

@@ -0,0 +1,146 @@
+import { createClient, Temv1alpha1 } from '@scaleway/sdk';
+import type { Region } from '@scaleway/sdk-client';
+import { Logger } from '@contractspec/lib.logger';
+import type {
+  EmailAddress,
+  EmailConfigResult,
+  EmailSendOutcome,
+  EmailServiceConfig,
+  SendEmailRequest,
+} from './types';
+
+const DEFAULT_FROM: EmailAddress = {
+  email: 'noreply@transactional.contractspec.io',
+  name: 'ContractSpec',
+};
+
+const DEFAULT_TEAM_INBOX: EmailAddress = {
+  email: 'contact@contractspec.io',
+  name: 'ContractSpec Team',
+};
+
+const DEFAULT_REGION: Region = 'fr-par';
+
+type EmailApi = Pick<Temv1alpha1.API, 'createEmail'>;
+
+let cachedConfig: EmailServiceConfig | null = null;
+let cachedClient: EmailApi | null = null;
+let apiFactory: (client: ReturnType<typeof createClient>) => EmailApi = (
+  client
+) => new Temv1alpha1.API(client);
+
+const mapRegion = (value?: string | null): Region => {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === 'par' || normalized === 'fr-par') return 'fr-par';
+  if (normalized === 'ams' || normalized === 'nl-ams') return 'nl-ams';
+  if (normalized === 'waw' || normalized === 'pl-waw') return 'pl-waw';
+  return DEFAULT_REGION;
+};
+
+export const getEmailConfig = (): EmailConfigResult => {
+  if (cachedConfig) {
+    return { ok: true, config: cachedConfig };
+  }
+
+  const accessKey =
+    process.env.SCALEWAY_ACCESS_KEY || process.env.SCALEWAY_ACCESS_KEY_QUEUE;
+  const secretKey =
+    process.env.SCALEWAY_SECRET_KEY || process.env.SCALEWAY_SECRET_KEY_QUEUE;
+  const projectId = process.env.SCALEWAY_PROJECT_ID;
+
+  if (!accessKey || !secretKey || !projectId) {
+    return {
+      ok: false,
+      errorMessage:
+        'Email service is not configured. Please contact us directly at contact@contractspec.io.',
+    };
+  }
+
+  const region = mapRegion(process.env.SCALEWAY_REGION);
+
+  cachedConfig = {
+    accessKey,
+    secretKey,
+    projectId,
+    region,
+    defaultZone: `${region}-1`,
+    from: {
+      email: process.env.SCALEWAY_EMAIL_FROM_EMAIL ?? DEFAULT_FROM.email,
+      name: process.env.SCALEWAY_EMAIL_FROM_NAME ?? DEFAULT_FROM.name,
+    },
+    teamInbox: {
+      email: process.env.SCALEWAY_EMAIL_TEAM_EMAIL ?? DEFAULT_TEAM_INBOX.email,
+      name: process.env.SCALEWAY_EMAIL_TEAM_NAME ?? DEFAULT_TEAM_INBOX.name,
+    },
+  };
+
+  return { ok: true, config: cachedConfig };
+};
+
+const getTemClient = (config: EmailServiceConfig): EmailApi => {
+  if (cachedClient) {
+    return cachedClient;
+  }
+
+  const client = createClient({
+    accessKey: config.accessKey,
+    secretKey: config.secretKey,
+    defaultProjectId: config.projectId,
+    defaultRegion: config.region,
+    defaultZone: config.defaultZone,
+  });
+
+  cachedClient = apiFactory(client);
+  return cachedClient;
+};
+
+export const sendEmail = async (
+  config: EmailServiceConfig,
+  request: SendEmailRequest
+): Promise<EmailSendOutcome> => {
+  try {
+    const client = getTemClient(config);
+
+    await client.createEmail({
+      region: config.region,
+      projectId: config.projectId,
+      from: config.from,
+      to: request.to,
+      subject: request.subject,
+      text: request.text,
+      html: request.html || request.text,
+      additionalHeaders: request.replyTo
+        ? [{ key: 'Reply-To', value: request.replyTo }]
+        : undefined,
+    });
+
+    return { success: true };
+  } catch (error) {
+    new Logger().error('scaleway_tem_email_send_failed', {
+      context: request.context ?? 'email',
+      error: error instanceof Error ? error.message : error,
+    });
+    return {
+      success: false,
+      error,
+      errorMessage: 'Failed to send email via Scaleway.',
+    };
+  }
+};
+
+export const __internal = {
+  resetCaches() {
+    cachedClient = null;
+    cachedConfig = null;
+    apiFactory = (client: ReturnType<typeof createClient>) =>
+      new Temv1alpha1.API(client);
+  },
+  setApiFactory(
+    factory: (client: ReturnType<typeof createClient>) => EmailApi
+  ) {
+    apiFactory = factory;
+  },
+  setClient(client: EmailApi) {
+    cachedClient = client;
+  },
+};

package/src/libs/email/contact.ts

@@ -0,0 +1,80 @@
+'use server';
+
+import { getEmailConfig, sendEmail } from './client';
+import { escapeHtml, formatMultilineHtml } from './utils';
+import type { SubmitContactFormResult } from './types';
+
+const CONTACT_MISSING_CONFIG =
+  'Email service is not configured. Please contact us directly at contact@contractspec.io.';
+const CONTACT_SEND_ERROR =
+  'Failed to send message. Please contact us directly at contact@contractspec.io.';
+
+export const submitContactForm = async (
+  formData: FormData
+): Promise<SubmitContactFormResult> => {
+  const name = (formData.get('name') ?? '').toString().trim();
+  const email = (formData.get('email') ?? '').toString().trim();
+  const message = (formData.get('message') ?? '').toString().trim();
+
+  if (!email) {
+    return {
+      success: false,
+      text: 'Please fill in all required fields.',
+    };
+  }
+
+  const configResult = getEmailConfig();
+  if (!configResult.ok || !configResult.config) {
+    return {
+      success: false,
+      text: configResult.errorMessage ?? CONTACT_MISSING_CONFIG,
+    };
+  }
+
+  const senderName = name || email;
+  const emailContentText = `
+New contact form submission from ${senderName}
+
+Contact Information:
+- Name: ${name || 'Not provided'}
+- Email: ${email}
+
+Message:
+${message || 'No message provided'}
+
+---
+Submitted via ContractSpec contact form
+  `.trim();
+
+  const emailContentHtml = `
+    <div style="font-family: sans-serif; max-width: 640px; margin: 0 auto;">
+      <h1 style="color: #8b5cf6; margin-bottom: 12px;">New contact form submission</h1>
+      <p style="margin: 0 0 12px;">From ${escapeHtml(senderName)}</p>
+      <h2 style="color: #8b5cf6; margin: 16px 0 8px;">Contact Information</h2>
+      <ul style="padding-left: 16px; line-height: 1.6; margin: 0 0 16px;">
+        <li>Name: ${escapeHtml(name || 'Not provided')}</li>
+        <li>Email: ${escapeHtml(email)}</li>
+      </ul>
+      <h2 style="color: #8b5cf6; margin: 16px 0 8px;">Message</h2>
+      <div style="border: 1px solid #e5e7eb; border-radius: 8px; padding: 12px; background: #f9fafb; white-space: pre-wrap; line-height: 1.6;">
+        ${message ? formatMultilineHtml(message) : 'No message provided'}
+      </div>
+      <p style="color: #6b7280; font-size: 12px; margin-top: 20px;">Submitted via ContractSpec contact form</p>
+    </div>
+  `;
+
+  const sendResult = await sendEmail(configResult.config, {
+    to: [configResult.config.teamInbox],
+    subject: `New Contact Form Message from ${senderName}`,
+    text: emailContentText,
+    html: emailContentHtml,
+    replyTo: email,
+    context: 'contact-form',
+  });
+
+  if (!sendResult.success) {
+    return { success: false, text: CONTACT_SEND_ERROR };
+  }
+
+  return { success: true, text: 'Message sent successfully!' };
+};

package/src/libs/email/newsletter.ts

@@ -0,0 +1,108 @@
+'use server';
+
+import { getEmailConfig, sendEmail } from './client';
+import { formatMultilineHtml } from './utils';
+import type { SubmitNewsletterResult } from './types';
+
+const NEWSLETTER_MISSING_CONFIG =
+  'Newsletter service is not configured. Please try again later.';
+const NEWSLETTER_SEND_ERROR =
+  'Failed to subscribe. Please try again later or contact us directly.';
+
+export const subscribeToNewsletter = async (
+  formData: FormData
+): Promise<SubmitNewsletterResult> => {
+  const email = (formData.get('email') ?? '').toString().trim();
+
+  if (!email || !email.includes('@')) {
+    return {
+      success: false,
+      text: 'Please enter a valid email address.',
+    };
+  }
+
+  const configResult = getEmailConfig();
+  if (!configResult.ok || !configResult.config) {
+    return {
+      success: false,
+      text: configResult.errorMessage ?? NEWSLETTER_MISSING_CONFIG,
+    };
+  }
+
+  const welcomeText = `
+Welcome to ContractSpec!
+
+Thanks for subscribing to our newsletter. You'll receive updates on:
+
+• New integrations (Stripe, OpenAI, Qdrant, and more)
+• Product features and improvements
+• New templates and examples
+• Architecture insights and best practices
+• Documentation updates
+
+Stay tuned for exciting updates!
+
+---
+ContractSpec Team
+https://contractspec.io
+
+Unsubscribe: Reply to this email with "unsubscribe"
+  `.trim();
+
+  const welcomeHtml = `
+    <div style="font-family: sans-serif; max-width: 640px; margin: 0 auto;">
+      <h1 style="color: #8b5cf6;">Welcome to ContractSpec!</h1>
+      <p>Thanks for subscribing to our newsletter. You'll receive updates on:</p>
+      <ul style="line-height: 1.8;">
+        <li>New integrations (Stripe, OpenAI, Qdrant, and more)</li>
+        <li>Product features and improvements</li>
+        <li>New templates and examples</li>
+        <li>Architecture insights and best practices</li>
+        <li>Documentation updates</li>
+      </ul>
+      <p>Stay tuned for exciting updates!</p>
+      <hr style="margin: 30px 0; border: none; border-top: 1px solid #e5e7eb;" />
+      <p style="color: #6b7280; font-size: 14px;">
+        ContractSpec Team<br />
+        <a href="https://contractspec.io" style="color: #8b5cf6;">contractspec.io</a>
+      </p>
+      <p style="color: #9ca3af; font-size: 12px;">
+        To unsubscribe, reply to this email with "unsubscribe"
+      </p>
+    </div>
+  `;
+
+  const userSend = await sendEmail(configResult.config, {
+    to: [{ email }],
+    subject: 'Welcome to ContractSpec Newsletter',
+    text: welcomeText,
+    html: welcomeHtml,
+    context: 'newsletter-welcome',
+  });
+
+  if (!userSend.success) {
+    return { success: false, text: NEWSLETTER_SEND_ERROR };
+  }
+
+  const teamNotificationText = `New newsletter subscription from: ${email}`;
+  const teamNotificationHtml = `
+    <div style="font-family: sans-serif; max-width: 640px; margin: 0 auto;">
+      <p style="margin: 0 0 8px;">New newsletter subscription</p>
+      <p style="margin: 0;"><strong>Email:</strong> ${formatMultilineHtml(email)}</p>
+    </div>
+  `;
+
+  const teamSend = await sendEmail(configResult.config, {
+    to: [configResult.config.teamInbox],
+    subject: `New Newsletter Subscription: ${email}`,
+    text: teamNotificationText,
+    html: teamNotificationHtml,
+    context: 'newsletter-team-notification',
+  });
+
+  if (!teamSend.success) {
+    return { success: false, text: NEWSLETTER_SEND_ERROR };
+  }
+
+  return { success: true, text: 'Successfully subscribed!' };
+};