This repository contains comprehensive documentation for integrating with Karpeles Lab Inc systems and APIs.
- API Basics - Documentation for working with the PHP Platform REST API
- Access Levels - Guide for understanding access levels, permissions, and user groups
- OAuth2 Authentication - Guide for OAuth2 token authentication and API key signing
- User Flow - Guide for implementing user authentication and registration flows
- KLB API Describe Tool - Manual for using the klbfw-describe command-line tool for API exploration
- KLB Framework JavaScript - Documentation for the JavaScript framework integration
- KLB Framework i18n - Guide for implementing internationalization with i18next
- KLB Framework Flutter - Documentation for the Flutter package integration
- Stripe Express Checkout - Guide for implementing Stripe Express Checkout (Apple Pay, Google Pay)
- Site AI Chat - Guide for letting site visitors chat with an AI that can search the catalog and manage their cart
- Frontend HTMX - Guide for building server-rendered frontends using HTMX with the platform's templating system
- Media Variations API - Documentation for transforming media files through API endpoints
- Version Service Worker - Guide for setting up a service worker for version tracking in Vue.js apps
- Upload Protocol - Low-level upload protocol for client implementations without a native SDK
This documentation provides detailed information for developers integrating with Karpeles Lab Inc systems. The guides cover both API endpoints and user interface integration requirements.
The API Basics guide covers:
- Authentication methods
- Request and response formats
- HTTP status codes
- Error handling
- Pagination
- Resource operations
- Query filters
- Rate limiting
- Example requests
The Access Levels guide covers:
- Access level hierarchy (O, A, D, W, C, R, N)
- User groups and group membership
- How access checks work
- Understanding the
accessproperty in API responses - Public resources and link-based sharing
- Parent-child access inheritance
The OAuth2 Authentication guide covers:
- OAuth2 bearer token authentication for user sessions
- Token refresh flow and automatic renewal
- API key authentication using Ed25519 signatures
- Request signing for server-to-server communication
- Error handling and best practices
The User Flow guide covers:
- Step-by-step process for user authentication and registration
- API response format
- UI element specifications
- Common flow actions
- Implementation guidelines
- Security considerations
- Example flows
The KLB API Describe Tool manual covers:
- Installation and basic usage
- Command-line options
- Output formats (formatted, raw JSON, TypeScript)
- Understanding different API endpoint types
- Best practices for API discovery and integration
- Calling conventions and API path structure
- Troubleshooting and common issues
The KLB Framework JavaScript documentation covers:
- Setting up and integrating the JavaScript framework
- Available components and utilities
- Authentication integration
- API communication
- Event handling
- Client-side validation
- Examples and usage patterns
The KLB Framework i18n guide covers:
- Setting up internationalization with i18next
- Preparing CSV translation files
- Using translations in your code
- Language detection
- Troubleshooting and best practices
The KLB Framework Flutter documentation covers:
- Installing and initializing the Flutter package
- Authentication with OAuth2
- Making API requests (authenticated, unauthenticated, optional authentication)
- User management features
- File uploads with progress tracking
- Deep link handling
- Error handling
The Stripe Express Checkout guide covers:
- Integrating Stripe Express Checkout in Vue.js applications
- Setting up Apple Pay and Google Pay buttons
- Handling both express checkout and standard card payments
- Creating orders on-the-fly during payment
- Managing the complete payment lifecycle
- Handling redirects and payment confirmations
- Testing express checkout in development
The Frontend HTMX guide covers:
- Setting up HTMX mode for server-rendered frontends
- Template directives (klb-if, klb-loop, klb-i18n)
- REST API integration with klb-rest elements
- HTMX response control directives
- Routing and URL patterns
- Security features (CSP nonce, session tokens)
The Media Variations API documentation covers:
- Requesting transformed versions of images and audio files
- Available filters for image processing (scaling, effects, format conversion)
- Audio format conversion and processing options
- Handling multi-page documents and PDFs
- Best practices for responsive images and media optimization
- Performance considerations and CDN delivery
The Version Service Worker guide covers:
- Setting up a service worker that adds version headers to asset requests
- Implementing version tracking using Git commit hashes
- Configuring webpack plugins for automatic version injection
- Integrating version information into Vue.js applications
- Enabling better cache management and version-specific routing
- Browser compatibility and troubleshooting
The Upload Protocol specification covers:
- Low-level upload protocol for environments without a native klbfw SDK
- Two-phase upload process (negotiation and transfer)
- Direct PUT upload method with chunking support
- AWS S3 multipart upload method with request signing
- Error handling and retry behavior
- Implementation checklists and example code
The Site AI Chat guide covers:
- Chat subjects: per-realm AI chat configuration (prompt, model, tools, limits)
- Anonymous and logged-in visitor chats
- Catalog search and cart tools available to the AI
- Creating chats, sending messages and displaying the conversation
- Managing subjects as a realm administrator
- Review the API Basics document to understand how to authenticate and make API requests
- Understand the Access Levels to work with permissions and user groups
- Learn about OAuth2 Authentication for token management and API key signing
- Follow the User Flow documentation to implement user authentication and registration
- Use the KLB API Describe Tool to explore and understand available API endpoints
- Integrate the KLB Framework JavaScript for client-side implementation
- Set up i18n with i18next for multi-language support
- Use the KLB Framework Flutter for mobile application development
- Implement Stripe Express Checkout for streamlined payment processing
- Build server-rendered frontends with Frontend HTMX integration
- Utilize Media Variations API for optimized media delivery
- Set up Version Service Worker for asset version tracking
- Add a Site AI Chat to let visitors find products and fill their cart
When working with Claude on KLB system projects, add the describe MCP tool to claude (replace "project" with "user" for global usage):
claude mcp add klbfw-describe -s project -- npx -y @karpeleslab/klbfw-describe --mcp
For support or questions about integrating with Karpeles Lab Inc systems, please contact the development team.