raffel 0.1.2

package/dist/mcp/docs/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../../../src/mcp/docs/adapters.ts"],"names":[],"mappings":"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"}

package/dist/mcp/docs/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Raffel MCP - Error Documentation
+ *
+ * Common errors with explanations, causes, and solutions.
+ */
+import type { RaffelErrorDoc } from '../types.js';
+export declare const errors: RaffelErrorDoc[];
+export declare function getError(code: string): RaffelErrorDoc | undefined;
+export declare function listErrors(): RaffelErrorDoc[];
+export declare function searchErrors(query: string): RaffelErrorDoc[];
+//# sourceMappingURL=errors.d.ts.map

package/dist/mcp/docs/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/mcp/docs/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,eAAO,MAAM,MAAM,EAAE,cAAc,EAgiBlC,CAAA;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEjE;AAED,wBAAgB,UAAU,IAAI,cAAc,EAAE,CAE7C;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,CAQ5D"}

package/dist/mcp/docs/errors.js

@@ -0,0 +1,549 @@
+/**
+ * Raffel MCP - Error Documentation
+ *
+ * Common errors with explanations, causes, and solutions.
+ */
+export const errors = [
+    // === Validation Errors ===
+    {
+        code: 'INVALID_ARGUMENT',
+        message: 'Request validation failed',
+        description: 'The input provided does not match the expected schema. This happens when required fields are missing, types are wrong, or values fail validation constraints.',
+        possibleCauses: [
+            'Missing required field in request body',
+            'Field type mismatch (e.g., string instead of number)',
+            'Value fails validation (e.g., email format, min/max length)',
+            'Extra fields not allowed in strict mode',
+            'Nested object validation failure',
+        ],
+        solutions: [
+            'Check the procedure input schema for required fields and types',
+            'Ensure all values match the expected types',
+            'Review validation constraints (min, max, pattern, format)',
+            'Use the procedure documentation to see the expected input shape',
+            'Check the error details for specific field errors',
+        ],
+        examples: [
+            {
+                title: 'Reading Validation Errors',
+                code: `// Error response structure
+{
+  "error": {
+    "code": "INVALID_ARGUMENT",
+    "message": "Request validation failed",
+    "details": {
+      "errors": [
+        { "field": "email", "message": "Invalid email format" },
+        { "field": "age", "message": "Must be at least 18" }
+      ]
+    }
+  }
+}
+
+// Fix by providing valid data
+const response = await client.call('users.create', {
+  email: 'valid@example.com',  // Valid email
+  age: 25                       // >= 18
+})`,
+            },
+        ],
+    },
+    {
+        code: 'UNAUTHENTICATED',
+        message: 'Authentication required',
+        description: 'The request requires authentication but no valid credentials were provided. This differs from PERMISSION_DENIED - this means no identity at all.',
+        possibleCauses: [
+            'Missing Authorization header',
+            'Invalid or expired token',
+            'Malformed credentials',
+            'Token signature verification failed',
+            'API key not provided or invalid',
+        ],
+        solutions: [
+            'Include a valid Authorization header with Bearer token',
+            'Check if the token has expired and refresh it',
+            'Verify the token format (Bearer <token>)',
+            'Ensure API key is correct if using API key auth',
+            'Login again to get a fresh token',
+        ],
+        examples: [
+            {
+                title: 'Adding Authentication',
+                code: `// Wrong: Missing auth
+await client.call('users.me', {})
+// Error: UNAUTHENTICATED
+
+// Correct: With Bearer token
+await client.call('users.me', {}, {
+  headers: {
+    Authorization: 'Bearer eyJhbGciOiJIUzI1NiIs...'
+  }
+})
+
+// Or with API key
+await client.call('users.me', {}, {
+  headers: {
+    'X-API-Key': 'your-api-key'
+  }
+})`,
+            },
+        ],
+    },
+    {
+        code: 'PERMISSION_DENIED',
+        message: 'Access denied',
+        description: 'The authenticated user does not have permission to perform this action. Unlike UNAUTHENTICATED, this means identity is known but lacks authorization.',
+        possibleCauses: [
+            'User lacks required role (e.g., admin)',
+            'User cannot access this resource (ownership)',
+            'Action not allowed for user tier/plan',
+            'Resource is restricted to certain users',
+            'Authorization policy denies the action',
+        ],
+        solutions: [
+            'Check if the user has the required role',
+            'Verify resource ownership if applicable',
+            'Review authorization rules for this procedure',
+            'Contact admin for elevated permissions',
+            "Ensure you're accessing resources you own",
+        ],
+        examples: [
+            {
+                title: 'Role-Based Access',
+                code: `// User without admin role
+await client.call('admin.deleteUser', { userId: '123' })
+// Error: PERMISSION_DENIED - Admin access required
+
+// Server-side authorization
+server.procedure('admin.deleteUser')
+  .use(requireAuth())
+  .use(hasRole('admin'))  // This check fails
+  .handler(async (input, ctx) => {
+    // Only admins reach here
+  })`,
+            },
+        ],
+    },
+    {
+        code: 'NOT_FOUND',
+        message: 'Resource not found',
+        description: 'The requested resource does not exist. This could be a procedure that does not exist or data that was not found.',
+        possibleCauses: [
+            'Procedure name is misspelled',
+            'Resource ID does not exist in database',
+            'Resource was deleted',
+            'Wrong endpoint or path',
+            'Procedure not registered on server',
+        ],
+        solutions: [
+            'Verify the procedure name is correct',
+            'Check if the resource ID exists',
+            'Use list endpoints to find valid IDs',
+            'Review available procedures with introspection',
+            'Check server logs for registration issues',
+        ],
+        examples: [
+            {
+                title: 'Handling Not Found',
+                code: `// Wrong: Typo in procedure name
+await client.call('user.get', { id: '123' })  // Should be 'users.get'
+// Error: NOT_FOUND - Procedure not found
+
+// Correct
+await client.call('users.get', { id: '123' })
+
+// Wrong: Non-existent resource
+await client.call('users.get', { id: 'non-existent-id' })
+// Error: NOT_FOUND - User not found
+
+// Handle in code
+try {
+  const user = await client.call('users.get', { id })
+} catch (error) {
+  if (error.code === 'NOT_FOUND') {
+    console.log('User does not exist')
+  }
+}`,
+            },
+        ],
+    },
+    {
+        code: 'ALREADY_EXISTS',
+        message: 'Resource already exists',
+        description: 'Attempted to create a resource that already exists. Common with unique constraints like email or username.',
+        possibleCauses: [
+            'Email already registered',
+            'Username taken',
+            'Unique constraint violation',
+            'Duplicate ID provided',
+            'Resource with same key exists',
+        ],
+        solutions: [
+            'Check if resource exists before creating',
+            'Use a different unique identifier',
+            'Update existing resource instead of creating',
+            'Handle the error and prompt user for different value',
+            'Use upsert operation if available',
+        ],
+        examples: [
+            {
+                title: 'Duplicate Email',
+                code: `// First registration succeeds
+await client.call('users.register', { email: 'user@example.com', ... })
+// OK
+
+// Second registration with same email fails
+await client.call('users.register', { email: 'user@example.com', ... })
+// Error: ALREADY_EXISTS - Email already registered
+
+// Handle gracefully
+try {
+  await client.call('users.register', input)
+} catch (error) {
+  if (error.code === 'ALREADY_EXISTS') {
+    showError('This email is already registered. Try logging in.')
+  }
+}`,
+            },
+        ],
+    },
+    {
+        code: 'RESOURCE_EXHAUSTED',
+        message: 'Rate limit exceeded',
+        description: 'Too many requests in a short period. Rate limiting is protecting the server from overload.',
+        possibleCauses: [
+            'Too many API calls from same IP/user',
+            'Burst of requests exceeded limit',
+            'Quota exhausted for the time window',
+            'Concurrent request limit reached',
+            'API plan rate limit hit',
+        ],
+        solutions: [
+            'Implement exponential backoff retry',
+            'Reduce request frequency',
+            'Check rate limit headers for remaining quota',
+            'Batch operations where possible',
+            'Upgrade API plan for higher limits',
+        ],
+        examples: [
+            {
+                title: 'Handling Rate Limits',
+                code: `// Response includes rate limit info
+// Headers:
+// X-RateLimit-Limit: 100
+// X-RateLimit-Remaining: 0
+// X-RateLimit-Reset: 1704067200
+
+// Error: RESOURCE_EXHAUSTED - Rate limit exceeded
+
+// Implement retry with backoff
+async function callWithRetry(procedure, input, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await client.call(procedure, input)
+    } catch (error) {
+      if (error.code === 'RESOURCE_EXHAUSTED' && i < maxRetries - 1) {
+        const delay = Math.pow(2, i) * 1000  // 1s, 2s, 4s
+        await sleep(delay)
+        continue
+      }
+      throw error
+    }
+  }
+}`,
+            },
+        ],
+    },
+    {
+        code: 'DEADLINE_EXCEEDED',
+        message: 'Request timeout',
+        description: 'The request took longer than the allowed deadline. The operation may or may not have completed.',
+        possibleCauses: [
+            'Slow database query',
+            'External service timeout',
+            'Large data processing',
+            'Network latency',
+            'Server overload',
+        ],
+        solutions: [
+            'Increase timeout for slow operations',
+            'Optimize slow queries',
+            'Use pagination for large datasets',
+            'Consider async processing for long operations',
+            'Check server and database health',
+        ],
+        examples: [
+            {
+                title: 'Handling Timeouts',
+                code: `// Server sets timeout
+server.use(timeout({ ms: 30000 }))  // 30 second timeout
+
+// Or per-procedure
+server.use(forPattern('reports.*', timeout({ ms: 120000 })))
+
+// Client handling
+try {
+  const report = await client.call('reports.generate', input, {
+    timeout: 120000  // Client timeout
+  })
+} catch (error) {
+  if (error.code === 'DEADLINE_EXCEEDED') {
+    // Operation may have started - check status
+    const status = await client.call('reports.status', { jobId })
+  }
+}`,
+            },
+        ],
+    },
+    {
+        code: 'CANCELLED',
+        message: 'Request cancelled',
+        description: 'The request was cancelled, either by the client or due to AbortSignal. Partial work may have been done.',
+        possibleCauses: [
+            'Client disconnected',
+            'User cancelled the operation',
+            'AbortController.abort() called',
+            'Page navigation during request',
+            'Connection timeout',
+        ],
+        solutions: [
+            'This is often intentional - no action needed',
+            'Ensure cleanup of partial work in handlers',
+            'Use transactions for atomic operations',
+            'Check signal.aborted in long operations',
+            'Implement proper cancellation handling',
+        ],
+        examples: [
+            {
+                title: 'Cancellable Operations',
+                code: `// Client can cancel
+const controller = new AbortController()
+
+const promise = client.call('reports.generate', input, {
+  signal: controller.signal
+})
+
+// User clicks cancel
+cancelButton.onclick = () => controller.abort()
+
+// Server handles cancellation
+server.procedure('reports.generate')
+  .handler(async (input, ctx) => {
+    for (const chunk of data) {
+      if (ctx.signal.aborted) {
+        // Clean up partial work
+        await cleanup()
+        throw new RaffelError('CANCELLED', 'Operation cancelled')
+      }
+      await processChunk(chunk)
+    }
+  })`,
+            },
+        ],
+    },
+    {
+        code: 'INTERNAL',
+        message: 'Internal server error',
+        description: 'An unexpected error occurred on the server. This usually indicates a bug or unhandled exception.',
+        possibleCauses: [
+            'Unhandled exception in handler',
+            'Database connection error',
+            'Configuration error',
+            'Bug in server code',
+            'Dependency failure',
+        ],
+        solutions: [
+            'Check server logs for detailed error',
+            'Report the issue with request ID',
+            'Retry may help for transient errors',
+            'Contact support if persistent',
+            'Check service health dashboards',
+        ],
+        examples: [
+            {
+                title: 'Error Tracking',
+                code: `// Response includes request ID for debugging
+{
+  "error": {
+    "code": "INTERNAL",
+    "message": "Internal server error",
+    "requestId": "req_abc123"
+  }
+}
+
+// Report to support with request ID
+// Server logs show full stack trace for req_abc123
+
+// Retry for transient errors
+async function callWithRetry(procedure, input) {
+  for (let i = 0; i < 3; i++) {
+    try {
+      return await client.call(procedure, input)
+    } catch (error) {
+      if (error.code === 'INTERNAL' && i < 2) {
+        await sleep(1000)
+        continue
+      }
+      throw error
+    }
+  }
+}`,
+            },
+        ],
+    },
+    {
+        code: 'UNAVAILABLE',
+        message: 'Service unavailable',
+        description: 'The service is currently unavailable, often due to overload or maintenance. Try again later.',
+        possibleCauses: [
+            'Server is overloaded',
+            'Maintenance window',
+            'Dependency service down',
+            'Circuit breaker open',
+            'Deployment in progress',
+        ],
+        solutions: [
+            'Retry with exponential backoff',
+            'Check service status page',
+            'Wait and try again later',
+            'Use fallback if available',
+            'Check for maintenance announcements',
+        ],
+        examples: [
+            {
+                title: 'Service Unavailable Handling',
+                code: `// Circuit breaker is open
+server.use(forPattern('payments.*', circuitBreaker({
+  failureThreshold: 5,
+  timeout: 30000
+})))
+
+// When payment service fails 5 times:
+// Error: UNAVAILABLE - Circuit breaker open
+
+// Client retry with backoff
+const retryWithBackoff = async (fn, maxRetries = 5) => {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn()
+    } catch (error) {
+      if (error.code === 'UNAVAILABLE') {
+        const delay = Math.min(Math.pow(2, i) * 1000, 30000)
+        console.log(\`Service unavailable, retrying in \${delay}ms\`)
+        await sleep(delay)
+        continue
+      }
+      throw error
+    }
+  }
+  throw new Error('Service unavailable after max retries')
+}`,
+            },
+        ],
+    },
+    // === WebSocket Errors ===
+    {
+        code: 'WS_CONNECTION_FAILED',
+        message: 'WebSocket connection failed',
+        description: 'Failed to establish WebSocket connection to the server.',
+        possibleCauses: [
+            'Server not accepting WebSocket connections',
+            'Wrong WebSocket URL',
+            'Network connectivity issues',
+            'Firewall blocking WebSocket',
+            'SSL/TLS certificate issues',
+        ],
+        solutions: [
+            'Verify the WebSocket URL is correct',
+            'Check server has WebSocket enabled',
+            'Ensure network allows WebSocket connections',
+            'Check for SSL certificate errors',
+            'Try connecting via different network',
+        ],
+    },
+    {
+        code: 'WS_MESSAGE_TOO_LARGE',
+        message: 'WebSocket message too large',
+        description: 'The message exceeds the maximum allowed size for WebSocket.',
+        possibleCauses: [
+            'Sending very large payloads',
+            'Message exceeds server limit',
+            'Binary data too large',
+        ],
+        solutions: [
+            'Chunk large messages into smaller pieces',
+            'Use streaming for large data transfers',
+            'Compress payloads before sending',
+            'Increase server message limit if needed',
+        ],
+    },
+    // === gRPC Errors ===
+    {
+        code: 'GRPC_METADATA_TOO_LARGE',
+        message: 'gRPC metadata too large',
+        description: 'The gRPC metadata (headers) exceeds the maximum allowed size.',
+        possibleCauses: [
+            'Too many metadata entries',
+            'Large values in metadata',
+            'Token too long for metadata',
+        ],
+        solutions: [
+            'Reduce metadata size',
+            'Move large values to request body',
+            'Use shorter tokens if possible',
+        ],
+    },
+    // === Validation-specific ===
+    {
+        code: 'SCHEMA_NOT_FOUND',
+        message: 'Validation schema not registered',
+        description: 'Attempted to validate but no validator is registered. Must call registerValidator() first.',
+        possibleCauses: [
+            'Forgot to register validator adapter',
+            'registerValidator() not called before server start',
+            'Using schema type without corresponding adapter',
+        ],
+        solutions: [
+            'Call registerValidator(createZodAdapter(z)) at startup',
+            'Ensure validator registration before defining procedures',
+            'Check import paths for validator adapter',
+        ],
+        examples: [
+            {
+                title: 'Registering Validator',
+                code: `// WRONG - Forgot to register
+import { createServer } from 'raffel'
+import { z } from 'zod'
+
+const server = createServer()
+  .procedure('users.create')
+    .input(z.object({ name: z.string() }))  // Error: SCHEMA_NOT_FOUND
+    .handler(async (input) => {})
+
+// CORRECT
+import { createServer, registerValidator, createZodAdapter } from 'raffel'
+import { z } from 'zod'
+
+registerValidator(createZodAdapter(z))  // Register first!
+
+const server = createServer()
+  .procedure('users.create')
+    .input(z.object({ name: z.string() }))
+    .handler(async (input) => {})`,
+            },
+        ],
+    },
+];
+export function getError(code) {
+    return errors.find((e) => e.code === code);
+}
+export function listErrors() {
+    return errors;
+}
+export function searchErrors(query) {
+    const lowerQuery = query.toLowerCase();
+    return errors.filter((e) => e.code.toLowerCase().includes(lowerQuery) ||
+        e.message.toLowerCase().includes(lowerQuery) ||
+        e.description.toLowerCase().includes(lowerQuery));
+}
+//# sourceMappingURL=errors.js.map

package/dist/mcp/docs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/mcp/docs/errors.ts"],"names":[],"mappings":"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"}

package/dist/mcp/docs/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Raffel MCP - Documentation Index
+ *
+ * Central export for all documentation modules.
+ */
+export { interceptors, interceptorsByCategory, getInterceptor, listInterceptors, } from './interceptors.js';
+export { adapters, getAdapter, listAdapters } from './adapters.js';
+export { patterns, getPattern, listPatterns, searchPatterns } from './patterns.js';
+export { errors, getError, listErrors, searchErrors } from './errors.js';
+export { quickstartGuide, boilerplates, getBoilerplate, listBoilerplates } from './quickstart.js';
+export type { ComponentDoc, PropDoc, MethodDoc, ExampleDoc, InterceptorDoc, AdapterDoc, PatternDoc, HookDoc, GuideDoc, RaffelErrorDoc, } from '../types.js';
+export interface SearchResult {
+    type: 'interceptor' | 'adapter' | 'pattern' | 'error';
+    name: string;
+    description: string;
+    category?: string;
+}
+export declare function searchAll(query: string): SearchResult[];
+export declare const categories: {
+    interceptors: {
+        auth: string;
+        resilience: string;
+        observability: string;
+        validation: string;
+        caching: string;
+        composition: string;
+    };
+    adapters: {
+        http: string;
+        websocket: string;
+        grpc: string;
+        jsonrpc: string;
+        graphql: string;
+        tcp: string;
+        s3db: string;
+    };
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/docs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp/docs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,cAAc,EACd,gBAAgB,GACjB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAGlE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAGlF,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAGxE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAGjG,YAAY,EACV,YAAY,EACZ,OAAO,EACP,SAAS,EACT,UAAU,EACV,cAAc,EACd,UAAU,EACV,UAAU,EACV,OAAO,EACP,QAAQ,EACR,cAAc,GACf,MAAM,aAAa,CAAA;AAQpB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;IACrD,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,CAiEvD;AAGD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;CAkBtB,CAAA"}