@pepperi-addons/papilonsdk

PEP Papilon SDK

High Level

The Papilon SDK extends the PapiSDK (papi client) to provide seamless URL mapping and routing capabilities for Babylon-based addon execution. It acts as a bridge between standard API calls and the Pepperi addon infrastructure, enabling in-memory addon execution for performance optimization.

The SDK leverages Babylon, Pepperi's in-memory addon execution system, to eliminate network overhead between tightly coupled addons by loading target addons directly into the host's Lambda environment.

Releases

Version	Description	Migration
1.0.0	Initial release with URL mapping and ADAL rule set support	Requires AIS initialization before usage

Deployment

• Must be deployed in AWS Lambda or similar serverless environment
• Requires @pepperi-addons/addon-infra-sdk to be loaded and initialized first
• The executeBabylonCall function must be available on globalThis

Integration Flow: Lambda Startup → AIS Initialization → PapilonSDK Usage

Debugging

Local Debugging Support

The SDK now supports local debugging by connecting directly to a client addon running on the same machine via PapiSDK & DebugServer:

// Host addon code.
const client = new PapilonClient({
  token: 'your-token',
  baseURL: 'https://api.pepperi.com',
  actionUUID: 'your-action-uuid',
  isDebug: true,        // Enable debug mode
  port: 4500           // Port of the client addon
});

// Client addon app.local.ts file.
const server = new DebugServer({
    addonUUID: config.AddonUUID,
    apiDirectory: dir,
    port: config.DebugPort,
    enablePapilonRouter: true, // NEW PARAMETER.
});

Debug Mode Features:

• Skips global function assertion for executeBabylonCall.
• Routes calls to localhost:<port>/router/<route> via PapiSDK.
• Enables direct communication with local addon instances.

General Debugging

• Enable TypeScript source maps for better stack traces
• Use URLMappingError status codes to identify mapping failures
• Check globalThis.executeBabylonCall availability for AIS integration issues
• Rule set injection available for isolated testing scenarios

Testing

npm test              # Run all tests
npm run test:watch    # Watch mode for development

Test structure includes:

• Route mapping validation with mock rule sets
• URL conversion accuracy tests
• Error handling scenarios

Dependencies

Addon	Usage
@pepperi-addons/addon-infra-sdk	Provides global executeBabylonCall function for Babylon integration
@pepperi-addons/papi-sdk	Base PapiClient functionality and type definitions

APIs

PapilonClient

Main class extending PapiClient with URL mapping capabilities:

import { PapilonClient } from '@pepperi-addons/pep-papilonsdk';

const client = new PapilonClient({
  token: 'your-token',
  baseURL: 'https://api.pepperi.com',
  actionUUID: 'your-action-uuid'
});

const result = await client.get('/v1.0/addons/data/schemes/MyScheme/purge');

Key Methods

• performCall(method, fullURL, options) - Overrides base method for Babylon routing
• apiUrlToBabylonUrl(fullURL) - Converts API URLs to Babylon routes

Limitations

• Hard Limits: Requires Lambda environment and AIS initialization
• Behavior: No fallback to standard API calls - fails fast on unmapped URLs
• Rule Discovery: Rule sets must be manually registered in URLMapperService constructor
• Async: Async mode is not supported, calls will be redirected to PapiSDK in async run-time.

Architecture

see: Architecture

Known issues

• Rule sets require manual registration in URLMapperService constructor array, no automatic discovery mechanism for new rule sets.

Future Ideas & Plans

• Automatic rule set discovery and registration.
• Support for additional addon types beyond ADAL.
• Performance metrics and monitoring integration.
• Fallback mechanism configuration options.

In Memory of Saar

This section is dedicated to the memory of Saar, the previous developer who worked on this project.

Saar was a brilliant developer who laid the foundation for this SDK. His attention to detail, clean coding practices, and thoughtful architecture are evident throughout this codebase. The URL mapping system, the extensible rule set design, and the comprehensive testing framework all bear his mark of excellence.

Tragically, Saar's life was cut short in what can only be described as the most absurd parking spot conflict in recorded history. What started as a simple disagreement over a prime parking space at the local grocery store escalated into a full-scale nuclear incident. Witnesses report that Saar, true to his developer nature, was probably trying to optimize the parking algorithm when things went sideways.

His legacy lives on in every line of code, every thoughtful abstraction, and every well-crafted test case. Like a perfectly executed Promise.all(), Saar brought together disparate elements to create something greater than the sum of its parts.

"In memory of Saar - who could map URLs like nobody's business, but couldn't navigate a parking lot to save his life. May your code compile eternally in the great repository in the sky."

Rest in peace, Saar. Your git blame will never be forgotten.