@captcha-kit/core 1.0.0

package/README.md

@@ -0,0 +1,169 @@
+# MessageKit Core
+
+**MessageKit Core is a TypeScript library that provides foundational classes, interfaces, and tools for handling and processing messages within domain-driven and AI applications.** This package offers a set of abstractions that make it easier to manage messaging workflows, including sending and receiving messages across different channels.
+
+## Supported Packages
+
+The `@messagekit/core` package supports several email service providers, including:
+
+- **Mailgun**: Integration with the Mailgun email service for sending emails.
+- **Nylas**: Integration with the Nylas email service for sending emails.
+- **Resend**: Integration with the Resend email service for sending emails.
+- **SendGrid**: Integration with the SendGrid email service for sending emails.
+
+### Adding New Providers
+
+To add a new email provider, you can implement the `EmailProviderFactoryInterface` and `EmailSenderInterface`. Here’s a brief example of how to implement a new provider:
+
+1. **Create a New Folder**: Create a new folder for your provider (e.g., `packages/myprovider`).
+2. **Implement the Factory**: Create a factory class that implements the `EmailProviderFactoryInterface`. This class should have a method to create an email sender instance.
+
+   Example:
+   ```typescript
+   import { MyProviderEmailSender } from './Provider/MyProviderEmailSender';
+   import type { TypeMyProviderConfig } from './Type/Types';
+   import type { EmailProviderFactoryInterface, EmailSenderInterface } from '@messagekit/core';
+
+   export class MyProviderEmailProviderFactory implements EmailProviderFactoryInterface<TypeMyProviderConfig> {
+       public async createSender(config: TypeMyProviderConfig): Promise<EmailSenderInterface> {
+           return new MyProviderEmailSender(config);
+       }
+   }
+   ```
+
+3. **Implement the Email Sender**: Create a class that implements the `EmailSenderInterface`. This class should handle the logic for sending emails.
+
+   Example:
+   ```typescript
+   import type { TypeEmailMessage, TypeEmailMessageResponse, EmailSenderInterface } from '@messagekit/core';
+
+   export class MyProviderEmailSender implements EmailSenderInterface {
+       constructor(private config: TypeMyProviderConfig) {}
+
+       public async send(message: TypeEmailMessage): Promise<TypeEmailMessageResponse> {
+           // Implement the logic to send the email using your provider's API
+           // It is recommended to use transformers and types for consistency
+       }
+   }
+   ```
+
+4. **Use Transformers and Types**: It is recommended to use transformers and types to ensure consistency in the data being processed. This helps maintain the expected structure and format across different email providers.
+
+### Folder Structure
+
+The folder structure for each package typically includes:
+
+- `src/`: Contains the source code for the package, including:
+  - `Factory/`: Contains factory classes for creating email providers.
+  - `Provider/`: Contains classes that implement the email sending logic.
+  - `Transformer/`: Contains classes for transforming email messages to the required format.
+  - `Type/`: Contains type definitions and interfaces.
+- `tests/`: Contains unit tests for the package.
+- `README.md`: Documentation for the package.
+- `.env`: Environment variables for configuration.
+
+## Installation
+
+Install the package using pnpm:
+
+```bash
+pnpm add @messagekit/core
+```
+
+## Features
+
+- **Unified Messaging Interfaces**: Define consistent interfaces for handling message-related actions, such as downloading attachments, sending messages, and handling webhooks.
+- **AI Integration Ready**: Tools are designed to wrap actions and services, allowing them to be easily integrated into AI workflows, especially with structured validation using Zod.
+- **Extensible and Reusable**: Easily extend the provided base classes and interfaces to fit your specific messaging needs.
+
+## Usage
+
+### Sending an Email
+
+The `sendEmail` function is the primary method for sending emails. It can be used as follows:
+
+```typescript
+import { sendEmail } from '@messagekit/core';
+
+const emailMessage = {
+  from: [{ email: 'sender@example.com', name: 'Sender Name' }],
+  to: [{ email: 'recipient@example.com', name: 'Recipient Name' }],
+  subject: 'Hello from MessageKit',
+  text: 'This is a test email sent using MessageKit.',
+  html: '<p>This is a test email sent using MessageKit.</p>',
+  attachments: [
+    {
+      content: 'base64-encoded-content',
+      filename: 'attachment.txt',
+      path: '/path/to/attachment.txt',
+    },
+  ],
+};
+
+const config = {
+  PROVIDER_NAME: process.env.PROVIDER_NAME, // any supported service from @messagekit/[PROVIDER_NAME]
+  RESEND_API_KEY: process.env.RESEND_API_KEY,
+  RESEND_API_URL: process.env.RESEND_API_URL,
+};
+
+sendEmail(emailMessage, config)
+  .then(response => {
+    console.log('Email sent successfully:', response);
+  })
+  .catch(error => {
+    console.error('Error sending email:', error);
+  });
+```
+
+### Configuration
+
+Configuration for the `sendEmail` function can be defined in a `.env` file. The naming convention for the configuration variables is as follows:
+
+- `PROVIDER_NAME`: The email service provider (e.g., 'sendgrid', 'mailgun', 'resend').
+- `RESEND_API_KEY`: The API key for authenticating with the Resend API, for Nylas it will be `NYLAS_API_KEY`, and so on...
+- `RESEND_API_URL`: An optional custom API URL.
+
+Example `.env` file:
+
+```
+RESEND_API_KEY=your_resend_api_key
+RESEND_API_URL=https://api.resend.com
+```
+
+### Extensibility
+
+The `@messagekit/core` package is designed to be extensible. You can create new email providers by implementing the `EmailProviderFactoryInterface` and `EmailSenderInterface`. This allows you to add support for additional email services in the future.
+
+## Rationale
+
+The `@messagekit/core` package is designed to provide a consistent and extensible foundation for managing messaging workflows in TypeScript applications. By using well-defined interfaces and tools, developers can easily integrate messaging capabilities into their domain-driven designs and AI-driven processes. The library also leverages Zod for schema validation, ensuring that the data being processed meets the expected structure.
+
+## Serverless Focus
+
+This package focuses on serverless (nodeless) environments, which is why it implements integrations with raw HTTP APIs.
+
+## Installation & Setup
+
+Install the package using pnpm:
+
+```bash
+pnpm add @messagekit/core
+pnpm add @messagekit/resend
+```
+
+Ensure that your project is set up to handle TypeScript and supports ES modules, as this library is built with modern JavaScript standards.
+
+## Contributing
+
+Contributions are welcome! Feel free to fork this project and submit pull requests. Before submitting, please ensure your code passes all linting and unit tests.
+
+You can format code using:
+
+```bash
+pnpm format
+```
+
+You can run unit tests using:
+
+```bash
+pnpm test

package/dist/Factory/CaptchaFactory.d.ts

@@ -0,0 +1,16 @@
+import type { CaptchaInterface } from '../Interface/index.js';
+import type { CaptchaFactoryInterface } from '../Interface/index.js';
+import type { TypeBaseConfig } from '../Type/index.js';
+/**
+ * Interface representing an captcha provider factory.
+ */
+export declare class CaptchaFactory implements CaptchaFactoryInterface<TypeBaseConfig> {
+    /**
+     * Creates an captcha based on the provided configuration.
+     *
+     * @param {TypeConfig} config - The configuration object for the email provider.
+     * @returns {Promise<CaptchaInterface>} - An captcha instance.
+     * @throws {Error} - Throws an error when requested provider captcha can't be created.
+     */
+    create(config: TypeBaseConfig): Promise<CaptchaInterface>;
+}

package/dist/Factory/CaptchaFactory.js

@@ -0,0 +1,32 @@
+/**
+ * Interface representing an captcha provider factory.
+ */
+export class CaptchaFactory {
+    /**
+     * Creates an captcha based on the provided configuration.
+     *
+     * @param {TypeConfig} config - The configuration object for the email provider.
+     * @returns {Promise<CaptchaInterface>} - An captcha instance.
+     * @throws {Error} - Throws an error when requested provider captcha can't be created.
+     */
+    async create(config) {
+        try {
+            const providerName = config.CAPTCHA_PROVIDER ?? 'core';
+            const packageName = '@captcha/' + providerName;
+            // Dynamically import the package and access the default export
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            const ProviderModule = await import(packageName);
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            const Factory = ProviderModule.default;
+            // we need to check if Factory has the create method, required by the EmailProviderFactoryInterface
+            if (typeof Factory !== 'function' || !('create' in Factory.prototype)) {
+                throw new Error('The provider module does not implement the required interface.');
+            }
+            // Instantiate the factory and create the captcha
+            return new Factory().create(config);
+        }
+        catch (error) {
+            throw new Error(`Failed to create a captcha for the provider "${config.CAPTCHA_PROVIDER}".`);
+        }
+    }
+}

package/dist/Factory/index.d.ts

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

package/dist/Factory/index.js

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

package/dist/Function/getCaptchaFormElement.d.ts

@@ -0,0 +1,8 @@
+import type { TypeBaseConfig } from '../Type/index.js';
+/**
+ * Gets the captcha form element for the provided configuration.
+ *
+ * @param {TypeBaseConfig} config - The configuration object for the captcha provider.
+ * @returns {Promise<React.FC>} - The captcha form element.
+ */
+export declare const getCaptchaFormElement: (config: TypeBaseConfig) => Promise<React.FC>;

package/dist/Function/getCaptchaFormElement.js

@@ -0,0 +1,8 @@
+import { CaptchaFactory } from '../Factory/index.js';
+/**
+ * Gets the captcha form element for the provided configuration.
+ *
+ * @param {TypeBaseConfig} config - The configuration object for the captcha provider.
+ * @returns {Promise<React.FC>} - The captcha form element.
+ */
+export const getCaptchaFormElement = async (config) => (await (new CaptchaFactory()).create(config)).getCaptchaFormElement();

package/dist/Function/getCaptchaScript.d.ts

@@ -0,0 +1,8 @@
+import type { TypeBaseConfig } from '../Type/index.js';
+/**
+ * Gets the captcha script for the provided configuration.
+ *
+ * @param {TypeBaseConfig} config - The configuration object for the captcha provider.
+ * @returns {Promise<React.FC>} - The captcha script.
+ */
+export declare const getCaptchaScript: (config: TypeBaseConfig) => Promise<React.FC>;

package/dist/Function/getCaptchaScript.js

@@ -0,0 +1,8 @@
+import { CaptchaFactory } from '../Factory/index.js';
+/**
+ * Gets the captcha script for the provided configuration.
+ *
+ * @param {TypeBaseConfig} config - The configuration object for the captcha provider.
+ * @returns {Promise<React.FC>} - The captcha script.
+ */
+export const getCaptchaScript = async (config) => (await (new CaptchaFactory()).create(config)).getCaptchaScript();

package/dist/Function/index.d.ts

@@ -0,0 +1,3 @@
+export * from './getCaptchaFormElement.js';
+export * from './getCaptchaScript.js';
+export * from './verifyCaptcha.js';

package/dist/Function/index.js

@@ -0,0 +1,3 @@
+export * from './getCaptchaFormElement.js';
+export * from './getCaptchaScript.js';
+export * from './verifyCaptcha.js';

package/dist/Function/verifyCaptcha.d.ts

@@ -0,0 +1,9 @@
+import type { TypeBaseConfig } from '../Type/index.js';
+/**
+ * Verifies the captcha response.
+ *
+ * @param {Record<string, any>} formFieldValues - The form field values to verify.
+ * @param {TypeBaseConfig} config - The configuration object for the captcha provider.
+ * @returns {Promise<boolean>} - Returns true if the captcha is verified.
+ */
+export declare const verifyCaptcha: (formFieldValues: Record<string, any>, config: TypeBaseConfig) => Promise<boolean>;

package/dist/Function/verifyCaptcha.js

@@ -0,0 +1,9 @@
+import { CaptchaFactory } from '../Factory/index.js';
+/**
+ * Verifies the captcha response.
+ *
+ * @param {Record<string, any>} formFieldValues - The form field values to verify.
+ * @param {TypeBaseConfig} config - The configuration object for the captcha provider.
+ * @returns {Promise<boolean>} - Returns true if the captcha is verified.
+ */
+export const verifyCaptcha = async (formFieldValues, config) => (await (new CaptchaFactory()).create(config)).verifyCaptcha(formFieldValues);

package/dist/Interface/CaptchaFactoryInterface.d.ts

@@ -0,0 +1,15 @@
+import type { TypeBaseConfig } from '../Type/Types.js';
+import type { CaptchaInterface } from './CaptchaInterface.js';
+/**
+ * Interface representing an captcha provider factory.
+ */
+export interface CaptchaFactoryInterface<TypeConfig extends TypeBaseConfig = TypeBaseConfig> {
+    /**
+     * Creates an captcha based on the provided configuration.
+     *
+     * @param {TypeConfig} config - The configuration object for the captcha provider.
+     * @returns {Promise<CaptchaInterface>} - An captcha instance.
+     * @throws {Error} - Throws an error when requested provider captcha can't be created.
+     */
+    create(config: TypeConfig): Promise<CaptchaInterface>;
+}

package/dist/Interface/CaptchaFactoryInterface.js

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

package/dist/Interface/CaptchaInterface.d.ts

@@ -0,0 +1,18 @@
+export interface CaptchaInterface {
+    /**
+     * Verify captcha
+     * @param {Record<string, any>} formFieldValues - Form field values
+     * @returns {Promise<boolean>} - Returns true if captcha is verified
+     */
+    verifyCaptcha(formFieldValues: Record<string, any>): Promise<boolean>;
+    /**
+     * Get captcha script
+     * @returns {React.FC} - Returns captcha script
+     */
+    getCaptchaScript(): React.FC;
+    /**
+     * Get captcha form element
+     * @returns {React.FC} - Returns captcha form element
+     */
+    getCaptchaFormElement(): React.FC;
+}

package/dist/Interface/CaptchaInterface.js

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

package/dist/Interface/index.d.ts

@@ -0,0 +1,2 @@
+export * from './CaptchaFactoryInterface.js';
+export * from './CaptchaInterface.js';

package/dist/Interface/index.js

@@ -0,0 +1,2 @@
+export * from './CaptchaFactoryInterface.js';
+export * from './CaptchaInterface.js';

package/dist/Type/Types.d.ts

@@ -0,0 +1,3 @@
+export interface TypeBaseConfig {
+    CAPTCHA_PROVIDER: string;
+}

package/dist/Type/Types.js

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

package/dist/Type/index.d.ts

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

package/dist/Type/index.js

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

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './Factory/index.js';
+export * from './Interface/index.js';
+export * from './Type/index.js';
+export * from './Function/index.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './Factory/index.js';
+export * from './Interface/index.js';
+export * from './Type/index.js';
+export * from './Function/index.js';

package/eslint.config.mjs

@@ -0,0 +1,6 @@
+import eslintConfig from '@dmitryrechkin/eslint-standard/eslint.config.mjs';
+
+export default eslintConfig({
+	tsconfigPath: './tsconfig.eslint.json',
+	ignores: ['packages/**', 'tests/**'],
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@captcha-kit/core",
+  "type": "module",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "devDependencies": {
+    "@dmitryrechkin/eslint-standard": "^1.0.7",
+    "fix-esm-import-path": "^1.0.1",
+    "dotenv": "^16.4.5",
+    "eslint": "^8.0.0",
+    "eslint-plugin-unused-imports": "^3.0.0",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.5.3",
+    "vitest": "^0.24.5",
+    "shx": "^0.3.4",
+    "@types/react": "^18.0.0"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "format": "eslint --fix .",
+    "test": "vitest run",
+    "check": "tsc --noEmit",
+    "build": "shx rm -rf dist && tsc && fix-esm-import-path dist",
+    "package:tgz": "pnpm pack",
+    "package:publish": "pnpm publish --access public"
+  }
+}

package/src/Factory/CaptchaFactory.ts

@@ -0,0 +1,44 @@
+import type { CaptchaInterface } from '../Interface';
+import type { CaptchaFactoryInterface } from '../Interface';
+import type { TypeBaseConfig } from '../Type';
+
+/**
+ * Interface representing an captcha provider factory.
+ */
+export class CaptchaFactory implements CaptchaFactoryInterface<TypeBaseConfig>
+{
+	/**
+	 * Creates an captcha based on the provided configuration.
+	 *
+	 * @param {TypeConfig} config - The configuration object for the email provider.
+	 * @returns {Promise<CaptchaInterface>} - An captcha instance.
+	 * @throws {Error} - Throws an error when requested provider captcha can't be created.
+	 */
+	public async create(config: TypeBaseConfig): Promise<CaptchaInterface>
+	{
+		try
+		{
+			const providerName = config.CAPTCHA_PROVIDER ?? 'core';
+			const packageName = '@captcha/' + providerName;
+
+			// Dynamically import the package and access the default export
+			// eslint-disable-next-line @typescript-eslint/naming-convention
+			const ProviderModule = await import(packageName);
+			// eslint-disable-next-line @typescript-eslint/naming-convention
+			const Factory = ProviderModule.default;
+
+			// we need to check if Factory has the create method, required by the EmailProviderFactoryInterface
+			if (typeof Factory !== 'function' || !('create' in Factory.prototype))
+			{
+				throw new Error('The provider module does not implement the required interface.');
+			}
+
+			// Instantiate the factory and create the captcha
+			return new Factory().create(config as any);
+		}
+		catch (error)
+		{
+			throw new Error(`Failed to create a captcha for the provider "${config.CAPTCHA_PROVIDER}".`);
+		}
+	}
+}

package/src/Factory/index.ts

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

package/src/Function/getCaptchaFormElement.tsx

@@ -0,0 +1,11 @@
+import type { TypeBaseConfig } from '../Type';
+import { CaptchaFactory } from '../Factory';
+
+/**
+ * Gets the captcha form element for the provided configuration.
+ *
+ * @param {TypeBaseConfig} config - The configuration object for the captcha provider.
+ * @returns {Promise<React.FC>} - The captcha form element.
+ */
+export const getCaptchaFormElement = async (config: TypeBaseConfig): Promise<React.FC> =>
+	(await (new CaptchaFactory()).create(config)).getCaptchaFormElement();

package/src/Function/getCaptchaScript.tsx

@@ -0,0 +1,11 @@
+import type { TypeBaseConfig } from '../Type';
+import { CaptchaFactory } from '../Factory';
+
+/**
+ * Gets the captcha script for the provided configuration.
+ *
+ * @param {TypeBaseConfig} config - The configuration object for the captcha provider.
+ * @returns {Promise<React.FC>} - The captcha script.
+ */
+export const getCaptchaScript = async (config: TypeBaseConfig): Promise<React.FC> =>
+	(await (new CaptchaFactory()).create(config)).getCaptchaScript();

package/src/Function/index.tsx

@@ -0,0 +1,3 @@
+export * from './getCaptchaFormElement';
+export * from './getCaptchaScript';
+export * from './verifyCaptcha';

package/src/Function/verifyCaptcha.ts

@@ -0,0 +1,12 @@
+import type { TypeBaseConfig } from '../Type';
+import { CaptchaFactory } from '../Factory';
+
+/**
+ * Verifies the captcha response.
+ *
+ * @param {Record<string, any>} formFieldValues - The form field values to verify.
+ * @param {TypeBaseConfig} config - The configuration object for the captcha provider.
+ * @returns {Promise<boolean>} - Returns true if the captcha is verified.
+ */
+export const verifyCaptcha = async (formFieldValues: Record<string, any>, config: TypeBaseConfig): Promise<boolean> =>
+	(await (new CaptchaFactory()).create(config)).verifyCaptcha(formFieldValues);

package/src/Interface/CaptchaFactoryInterface.ts

@@ -0,0 +1,17 @@
+import type { TypeBaseConfig } from '../Type/Types';
+import type { CaptchaInterface } from './CaptchaInterface';
+
+/**
+ * Interface representing an captcha provider factory.
+ */
+export interface CaptchaFactoryInterface<TypeConfig extends TypeBaseConfig = TypeBaseConfig>
+{
+	/**
+	 * Creates an captcha based on the provided configuration.
+	 *
+	 * @param {TypeConfig} config - The configuration object for the captcha provider.
+	 * @returns {Promise<CaptchaInterface>} - An captcha instance.
+	 * @throws {Error} - Throws an error when requested provider captcha can't be created.
+	 */
+	create(config: TypeConfig): Promise<CaptchaInterface>;
+}

package/src/Interface/CaptchaInterface.ts

@@ -0,0 +1,21 @@
+export interface CaptchaInterface
+{
+	/**
+	 * Verify captcha
+	 * @param {Record<string, any>} formFieldValues - Form field values
+	 * @returns {Promise<boolean>} - Returns true if captcha is verified
+	 */
+	verifyCaptcha(formFieldValues: Record<string, any>): Promise<boolean>;
+
+	/**
+	 * Get captcha script
+	 * @returns {React.FC} - Returns captcha script
+	 */
+	getCaptchaScript(): React.FC;
+
+	/**
+	 * Get captcha form element
+	 * @returns {React.FC} - Returns captcha form element
+	 */
+	getCaptchaFormElement(): React.FC;
+}

package/src/Interface/index.ts

@@ -0,0 +1,2 @@
+export * from './CaptchaFactoryInterface';
+export * from './CaptchaInterface';

package/src/Type/Types.ts

@@ -0,0 +1,6 @@
+// Base configuration for all configuration types, the expectation is that each provider will have its own configuration type that extends this.
+export interface TypeBaseConfig
+{
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	CAPTCHA_PROVIDER: string;
+}

package/src/Type/index.ts

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

package/src/index.tsx

@@ -0,0 +1,4 @@
+export * from './Factory';
+export * from './Interface';
+export * from './Type';
+export * from './Function';

package/tests/getCaptchaFormElement.test.tsx

@@ -0,0 +1,25 @@
+import { describe, it, expect, vi } from 'vitest';
+import { getCaptchaFormElement } from '../src/Function/getCaptchaFormElement';
+import type { TypeBaseConfig } from '../src/Type/Types';
+import React from 'react';
+
+vi.mock('../src/Factory', () => {
+	return {
+		CaptchaFactory: vi.fn().mockImplementation(() => {
+			return {
+				create: vi.fn().mockResolvedValue({
+					getCaptchaFormElement: () => () => <form>Mocked Form</form>
+				})
+			};
+		})
+	};
+});
+
+describe('getCaptchaFormElement', () => {
+	it('should return a React component for the captcha form element', async () => {
+		const config: TypeBaseConfig = { CAPTCHA_PROVIDER: 'test-provider' };
+		const formElement = await getCaptchaFormElement(config);
+		expect(formElement).toBeDefined();
+		expect(typeof formElement).toBe('function'); // Check if it's a React component
+	});
+});

package/tests/getCaptchaScript.test.tsx

@@ -0,0 +1,25 @@
+import { describe, it, expect, vi } from 'vitest';
+import { getCaptchaScript } from '../src/Function/getCaptchaScript';
+import type { TypeBaseConfig } from '../src/Type/Types';
+import React from 'react';
+
+vi.mock('../src/Factory', () => {
+	return {
+		CaptchaFactory: vi.fn().mockImplementation(() => {
+			return {
+				create: vi.fn().mockResolvedValue({
+					getCaptchaScript: () => () => <div>Mocked Script</div>
+				})
+			};
+		})
+	};
+});
+
+describe('getCaptchaScript', () => {
+	it('should return a React component for the captcha script', async () => {
+		const config: TypeBaseConfig = { CAPTCHA_PROVIDER: 'test-provider' };
+		const scriptComponent = await getCaptchaScript(config);
+		expect(scriptComponent).toBeDefined();
+		expect(typeof scriptComponent).toBe('function'); // Check if it's a React component
+	});
+});