vendure-plugin-capjs 0.0.1 → 1.0.1

package/README.md

@@ -1 +1,173 @@
-# Capjs plugin
+# Capjs Plugin
+
+A [Vendure](https://www.vendure.io/) plugin that integrates [Cap.js](https://capjs.js.org/) for privacy-focused, lightweight CAPTCHA protection. This plugin provides REST endpoints for challenge creation and redemption, along with a guard decorator for protecting GraphQL mutations.
+
+## Features
+
+- **Privacy-focused CAPTCHA**: Uses Cap.js proof-of-work challenges instead of tracking-based solutions
+- **GraphQL protection**: Easily protect any GraphQL mutation with a decorator
+- **REST endpoints**: `/cap/challenge` and `/cap/redeem` endpoints for frontend integration
+
+## Installation
+
+```bash
+npm install vendure-plugin-capjs @cap.js/server
+```
+
+## Configuration
+
+Add the plugin to your Vendure config:
+
+```typescript
+import { VendureConfig } from '@vendure/core';
+import { CapjsPlugin } from 'vendure-plugin-capjs';
+
+export const config: VendureConfig = {
+    // ... other config
+    plugins: [
+        CapjsPlugin.init({}),
+        // ... other plugins
+    ],
+};
+```
+
+## Database Migration
+
+This plugin adds new entities (`CapjsChallenges` and `CapjsToken`) to your database. After adding the plugin to your config, you need to generate and run a database migration:
+
+```bash
+# Generate the migration
+npm run migration:generate capjs-plugin
+
+# Run the migration
+npm run migration:run
+```
+
+Make sure your Vendure config has migrations enabled:
+
+```typescript
+export const config: VendureConfig = {
+    // ... other config
+    dbConnectionOptions: {
+        // ... other options
+        migrations: [/* your migrations */],
+        migrationsRun: false, // Set to true to run migrations automatically on startup
+    },
+};
+```
+
+## Usage
+
+### REST Endpoints
+
+The plugin exposes two REST endpoints:
+
+#### Create Challenge
+
+```
+POST /cap/challenge
+```
+
+Returns a new CAPTCHA challenge that the client must solve.
+
+#### Redeem Challenge
+
+```
+POST /cap/redeem
+Content-Type: application/json
+
+{
+  "token": "<challenge-token>",
+  "solutions": [<solution-numbers>]
+}
+```
+
+Validates the solved challenge and returns a token for subsequent API calls.
+
+### Protecting GraphQL Mutations
+
+Use the `@CapjsValidate()` decorator to protect any GraphQL mutation:
+
+```typescript
+import { Mutation, Resolver } from '@nestjs/graphql';
+import { CapjsValidate } from 'vendure-plugin-capjs';
+
+@Resolver()
+export class MyResolver {
+    @Mutation()
+    @CapjsValidate()
+    async submitForm() {
+        // This mutation is protected by CAPTCHA
+        // Will throw if x-captcha-token header is missing or invalid
+    }
+}
+```
+
+### Frontend Integration
+
+The client must:
+
+1. Request a challenge from `POST /cap/challenge`
+2. Solve the proof-of-work challenge using the [@cap.js/widget](https://www.npmjs.com/package/@cap.js/widget) or [@cap.js/vanilla](https://www.npmjs.com/package/@cap.js/vanilla)
+3. Submit solutions to `POST /cap/redeem` to get a validation token
+4. Include the token in the `x-captcha-token` header for protected GraphQL mutations
+
+Example with the Cap.js widget:
+
+```html
+<!-- Load the Cap.js widget script -->
+<script src="https://cdn.jsdelivr.net/npm/@cap.js/widget"></script>
+
+<!-- Add the widget to your form -->
+<cap-widget id="cap" data-cap-api-endpoint="/cap"></cap-widget>
+
+<script>
+    const widget = document.querySelector('#cap');
+
+    widget.addEventListener('solve', function (e) {
+        const token = e.detail.token;
+        // Include token in your GraphQL request headers
+        // headers: { 'x-captcha-token': token }
+    });
+</script>
+```
+
+For invisible mode (no visible widget):
+
+```javascript
+import Cap from '@cap.js/widget';
+
+const cap = new Cap({
+    apiEndpoint: '/cap/',
+});
+
+const token = await cap.solve();
+// Use token in x-captcha-token header
+```
+
+## API Reference
+
+### CapjsPlugin
+
+```typescript
+CapjsPlugin.init(options: PluginInitOptions)
+```
+
+Initializes the plugin with the given options.
+
+### CapjsValidate Decorator
+
+```typescript
+@CapjsValidate()
+```
+
+Decorator that applies the `CapjsGuard` to a resolver method. Validates the `x-captcha-token` header and throws a `UserInputError` if validation fails.
+
+### Error Codes
+
+- `MISSING_CAPTCHA`: The `x-captcha-token` header was not provided
+- `INVALID_CAPTCHA`: The provided token failed validation
+
+## License
+
+MIT

package/package.json

@@ -1,7 +1,9 @@
 {
     "name": "vendure-plugin-capjs",
-    "version": "0.0.1",
-    "license": "GPL-3.0-or-later",
+    "version": "1.0.1",
+    "description": "A Vendure plugin that integrates Cap.js for privacy-focused, lightweight CAPTCHA protection. Provides challenge/redeem endpoints and a guard decorator for protecting GraphQL mutations.",
+    "license": "MIT",
+    "private": false,
     "main": "lib/index.js",
     "types": "lib/index.d.ts",
     "files": [
@@ -16,7 +18,6 @@
         "lint": "eslint .",
         "test": "vitest --run"
     },
-    "private": false,
     "peerDependencies": {
         "@cap.js/server": "^4.0.5",
         "@google-cloud/pubsub": ">=4.0.0",
@@ -33,5 +34,11 @@
         "rimraf": "^5.0.5",
         "supertest": "^7.2.2",
         "typescript": "5.8.2"
-    }
+    },
+    "keywords": [
+        "vendure",
+        "vendure-plugin",
+        "capjs",
+        "captcha"
+    ]
 }