@parsrun/service-adapters 0.1.0

package/README.md

@@ -0,0 +1,166 @@
+# @parsrun/service-adapters
+
+Service definitions for Pars microservices - type-safe RPC contracts for email and payments.
+
+## Features
+
+- **Type-Safe**: Full TypeScript support for service contracts
+- **RPC Ready**: Compatible with @parsrun/service
+- **Reusable**: Share definitions between client and server
+- **Versioned**: Service versioning support
+
+## Installation
+
+```bash
+pnpm add @parsrun/service-adapters
+```
+
+## Quick Start
+
+```typescript
+import { emailService } from '@parsrun/service-adapters/email';
+import { createRpcClient } from '@parsrun/service/rpc';
+
+// Create type-safe client
+const email = createRpcClient({
+  service: emailService,
+  transport: httpTransport,
+});
+
+// Call with full type safety
+await email.call('send', {
+  to: 'user@example.com',
+  subject: 'Hello',
+  body: 'World',
+});
+```
+
+## API Overview
+
+### Email Service
+
+```typescript
+import { emailService, type EmailService } from '@parsrun/service-adapters/email';
+
+// Service definition
+emailService.name;      // 'email'
+emailService.version;   // '1.0.0'
+emailService.queries;   // { getStatus, ... }
+emailService.mutations; // { send, sendBatch, ... }
+emailService.events;    // { sent, failed, ... }
+```
+
+#### Queries
+
+| Method | Input | Output |
+|--------|-------|--------|
+| `getStatus` | `void` | `{ status, provider }` |
+| `getQuota` | `void` | `{ used, limit, resetAt }` |
+
+#### Mutations
+
+| Method | Input | Output |
+|--------|-------|--------|
+| `send` | `{ to, subject, body, ... }` | `{ messageId, status }` |
+| `sendBatch` | `{ messages[] }` | `{ results[] }` |
+| `sendTemplate` | `{ to, template, data }` | `{ messageId }` |
+
+#### Events
+
+| Event | Payload |
+|-------|---------|
+| `email.sent` | `{ messageId, to, subject }` |
+| `email.failed` | `{ messageId, error }` |
+| `email.bounced` | `{ messageId, reason }` |
+
+### Payments Service
+
+```typescript
+import { paymentsService, type PaymentsService } from '@parsrun/service-adapters/payments';
+
+// Service definition
+paymentsService.name;      // 'payments'
+paymentsService.version;   // '1.0.0'
+paymentsService.queries;   // { getSubscription, ... }
+paymentsService.mutations; // { createCheckout, ... }
+paymentsService.events;    // { subscriptionCreated, ... }
+```
+
+#### Queries
+
+| Method | Input | Output |
+|--------|-------|--------|
+| `getSubscription` | `{ subscriptionId }` | `Subscription` |
+| `getCustomer` | `{ customerId }` | `Customer` |
+| `listInvoices` | `{ customerId, limit? }` | `Invoice[]` |
+
+#### Mutations
+
+| Method | Input | Output |
+|--------|-------|--------|
+| `createCheckout` | `{ priceId, customerId, ... }` | `{ sessionId, url }` |
+| `cancelSubscription` | `{ subscriptionId }` | `{ success }` |
+| `updateSubscription` | `{ subscriptionId, priceId }` | `Subscription` |
+
+#### Events
+
+| Event | Payload |
+|-------|---------|
+| `subscription.created` | `{ subscriptionId, customerId }` |
+| `subscription.cancelled` | `{ subscriptionId, reason }` |
+| `payment.succeeded` | `{ paymentId, amount }` |
+| `payment.failed` | `{ paymentId, error }` |
+
+### Creating RPC Server
+
+```typescript
+import { emailService } from '@parsrun/service-adapters/email';
+import { createRpcServer } from '@parsrun/service/rpc';
+
+const server = createRpcServer({
+  service: emailService,
+  handlers: {
+    getStatus: async () => {
+      return { status: 'healthy', provider: 'resend' };
+    },
+    send: async ({ to, subject, body }) => {
+      const result = await emailProvider.send({ to, subject, body });
+      return { messageId: result.id, status: 'sent' };
+    },
+  },
+});
+```
+
+### Creating RPC Client
+
+```typescript
+import { emailService } from '@parsrun/service-adapters/email';
+import { createRpcClient, HttpTransport } from '@parsrun/service/rpc';
+
+const client = createRpcClient({
+  service: emailService,
+  transport: new HttpTransport({
+    baseUrl: 'https://api.example.com/rpc/email',
+  }),
+});
+
+// Type-safe calls
+const status = await client.query('getStatus');
+const result = await client.mutation('send', {
+  to: 'user@example.com',
+  subject: 'Hello',
+  body: 'World',
+});
+```
+
+## Exports
+
+```typescript
+import { ... } from '@parsrun/service-adapters';          // Main exports
+import { ... } from '@parsrun/service-adapters/email';    // Email service
+import { ... } from '@parsrun/service-adapters/payments'; // Payments service
+```
+
+## License
+
+MIT

package/dist/email/index.d.ts

@@ -0,0 +1,306 @@
+import * as _parsrun_service from '@parsrun/service';
+import { createMemoryEventTransport, RpcServer, EventEmitter, ServiceClientOptions } from '@parsrun/service';
+import { Logger } from '@parsrun/core';
+
+/**
+ * @parsrun/service-adapters - Email Service Definition
+ */
+/**
+ * Email Service Definition
+ *
+ * Provides email sending capabilities as a microservice.
+ */
+declare const emailServiceDefinition: _parsrun_service.ServiceDefinition<{
+    /**
+     * Check if email configuration is valid
+     */
+    verify: {
+        input: undefined;
+        output: {
+            valid: boolean;
+            provider: string;
+        };
+        description: string;
+    };
+    /**
+     * Get available email templates
+     */
+    getTemplates: {
+        input: undefined;
+        output: {
+            templates: Array<{
+                name: string;
+                description: string;
+                variables: string[];
+            }>;
+        };
+        description: string;
+    };
+}, {
+    /**
+     * Send a single email
+     */
+    send: {
+        input: {
+            to: string | string[];
+            subject: string;
+            html?: string;
+            text?: string;
+            from?: string;
+            replyTo?: string;
+            cc?: string | string[];
+            bcc?: string | string[];
+            templateName?: string;
+            templateData?: Record<string, unknown>;
+            tags?: Record<string, string>;
+            scheduledAt?: string;
+        };
+        output: {
+            success: boolean;
+            messageId?: string;
+            error?: string;
+        };
+        description: string;
+    };
+    /**
+     * Send batch emails
+     */
+    sendBatch: {
+        input: {
+            emails: Array<{
+                to: string | string[];
+                subject: string;
+                html?: string;
+                text?: string;
+                templateName?: string;
+                templateData?: Record<string, unknown>;
+            }>;
+            stopOnError?: boolean;
+        };
+        output: {
+            total: number;
+            successful: number;
+            failed: number;
+            results: Array<{
+                success: boolean;
+                messageId?: string;
+                error?: string;
+            }>;
+        };
+        description: string;
+    };
+    /**
+     * Render an email template
+     */
+    renderTemplate: {
+        input: {
+            templateName: string;
+            data: Record<string, unknown>;
+        };
+        output: {
+            subject: string;
+            html: string;
+            text: string;
+        };
+        description: string;
+    };
+}, {
+    /**
+     * Emitted when an email is sent successfully
+     */
+    "email.sent": {
+        data: {
+            messageId: string;
+            to: string[];
+            subject: string;
+            provider: string;
+            timestamp: string;
+        };
+        delivery: "at-least-once";
+        description: string;
+    };
+    /**
+     * Emitted when an email fails to send
+     */
+    "email.failed": {
+        data: {
+            to: string[];
+            subject: string;
+            error: string;
+            provider: string;
+            timestamp: string;
+        };
+        delivery: "at-least-once";
+        description: string;
+    };
+}, string[]>;
+/**
+ * Type export for the email service definition
+ */
+type EmailServiceDefinition = typeof emailServiceDefinition;
+
+/**
+ * @parsrun/service-adapters - Email Service Server
+ * Server-side implementation of the Email microservice
+ */
+
+interface EmailServiceServerOptions {
+    /** Email provider configuration */
+    provider: EmailProviderConfig;
+    /** Logger */
+    logger?: Logger;
+    /** Event transport (for emitting events) */
+    eventTransport?: ReturnType<typeof createMemoryEventTransport>;
+}
+interface EmailProviderConfig {
+    type: "resend" | "sendgrid" | "postmark" | "console";
+    apiKey?: string;
+    fromEmail: string;
+    fromName?: string;
+}
+/**
+ * Create Email Service Server
+ */
+declare function createEmailServiceServer(options: EmailServiceServerOptions): {
+    rpcServer: RpcServer;
+    eventEmitter: EventEmitter;
+    register: () => void;
+};
+
+/**
+ * @parsrun/service-adapters - Email Service Client
+ * Type-safe client for the Email microservice
+ */
+
+/**
+ * Type-safe Email Service Client
+ */
+interface EmailServiceClient {
+    /**
+     * Verify email provider configuration
+     */
+    verify(): Promise<{
+        valid: boolean;
+        provider: string;
+    }>;
+    /**
+     * Get available email templates
+     */
+    getTemplates(): Promise<{
+        templates: Array<{
+            name: string;
+            description: string;
+            variables: string[];
+        }>;
+    }>;
+    /**
+     * Send a single email
+     */
+    send(options: SendEmailOptions): Promise<SendEmailResult>;
+    /**
+     * Send batch emails
+     */
+    sendBatch(options: SendBatchOptions): Promise<SendBatchResult>;
+    /**
+     * Render an email template
+     */
+    renderTemplate(templateName: string, data: Record<string, unknown>): Promise<{
+        subject: string;
+        html: string;
+        text: string;
+    }>;
+    /**
+     * Subscribe to email events
+     */
+    onEmailSent(handler: (event: {
+        messageId: string;
+        to: string[];
+        subject: string;
+        provider: string;
+        timestamp: string;
+    }) => Promise<void>): () => void;
+    onEmailFailed(handler: (event: {
+        to: string[];
+        subject: string;
+        error: string;
+        provider: string;
+        timestamp: string;
+    }) => Promise<void>): () => void;
+    /**
+     * Close the client
+     */
+    close(): Promise<void>;
+}
+interface SendEmailOptions {
+    to: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    from?: string;
+    replyTo?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    templateName?: string;
+    templateData?: Record<string, unknown>;
+    tags?: Record<string, string>;
+    scheduledAt?: string;
+}
+interface SendEmailResult {
+    success: boolean;
+    messageId?: string;
+    error?: string;
+}
+interface SendBatchOptions {
+    emails: Array<{
+        to: string | string[];
+        subject: string;
+        html?: string;
+        text?: string;
+        templateName?: string;
+        templateData?: Record<string, unknown>;
+    }>;
+    stopOnError?: boolean;
+}
+interface SendBatchResult {
+    total: number;
+    successful: number;
+    failed: number;
+    results: Array<{
+        success: boolean;
+        messageId?: string;
+        error?: string;
+    }>;
+}
+/**
+ * Create Email Service Client
+ *
+ * @example
+ * ```typescript
+ * // Embedded mode (same process)
+ * const email = createEmailServiceClient();
+ *
+ * // HTTP mode (remote service)
+ * const email = createEmailServiceClient({
+ *   mode: 'http',
+ *   baseUrl: 'https://email.example.com',
+ * });
+ *
+ * // Send email
+ * const result = await email.send({
+ *   to: 'user@example.com',
+ *   subject: 'Hello',
+ *   html: '<p>Hello World</p>',
+ * });
+ *
+ * // Use template
+ * const result = await email.send({
+ *   to: 'user@example.com',
+ *   subject: 'Welcome!',
+ *   templateName: 'welcome',
+ *   templateData: { name: 'John', loginUrl: 'https://app.com/login' },
+ * });
+ * ```
+ */
+declare function createEmailServiceClient(options?: ServiceClientOptions): EmailServiceClient;
+
+export { type EmailServiceClient, type EmailServiceDefinition, type EmailServiceServerOptions, createEmailServiceClient, createEmailServiceServer, emailServiceDefinition };