Proxly SDK (@proxly/sdk)

This SDK provides the necessary functions for web applications running within the Proxly platform to interact with the secure host environment, user data, and AI models.

Installation

# Using pnpm (recommended in this workspace)
pnpm add @proxly/sdk

# Using npm
npm install @proxly/sdk

# Using yarn
yarn add @proxly/sdk

Core API Functions

The SDK exposes the following asynchronous functions:

getAppInfo(): Promise<AppInfo>

• Purpose: Fetches metadata about the currently running application itself.
• Returns: A promise resolving to an AppInfo object containing:
  • app_id: string: The unique identifier of the application.
  • name: string: The application's display name.
  • version: string: The application's version.
  • permissions?: Permission[]: (Optional) The list of permissions declared in the app's manifest.
• Permissions Required: None (implicitly granted).

requestPermission(permission: Permission): Promise<PermissionResult>

• Purpose: Requests user consent to grant a specific permission to the application.
• Parameters:
  • permission: Permission: A string representing the permission needed. This follows specific formats:
    • General: "ReadUserMemory", "WriteUserMemory", "NetworkAccess"
    • Key-specific Memory: `ReadUserMemory:${key}`, `WriteUserMemory:${key}` (e.g., "ReadUserMemory:user-settings")
    • Wildcard Memory: "ReadUserMemory:*", "WriteUserMemory:*"
    • Model-specific Execution: `RunModel:${modelId}` (e.g., "RunModel:llama3-instruct")
    • Wildcard Model Execution: "RunModel:*"
• Returns: A promise resolving to a PermissionResult object:
  • granted: boolean: Whether the user granted the permission.
  • error?: string: An error message if the request failed or was denied.
• Permissions Required: RequestPermission (implicitly granted to allow requesting others).

getUserMemory(key: string): Promise<MemoryReadResult>

• Purpose: Reads a value associated with a specific key from the user's secure shared memory store.
• Parameters:
  • key: string: The key identifying the data to retrieve.
• Returns: A promise resolving to a MemoryReadResult object:
  • success: boolean: Indicates if the read was successful.
  • value?: any: The retrieved value (if successful and exists).
  • error?: string: An error message if the read failed (e.g., permission denied, key not found).
• Permissions Required: ReadUserMemory (either wildcard * or specific permission matching the key).

setUserMemory(key: string, value: any): Promise<MemoryWriteResult>

• Purpose: Writes or updates a value associated with a specific key in the user's secure shared memory store.
• Parameters:
  • key: string: The key identifying the data location.
  • value: any: The data to store (must be JSON-serializable).
• Returns: A promise resolving to a MemoryWriteResult object:
  • success: boolean: Indicates if the write was successful.
  • error?: string: An error message if the write failed (e.g., permission denied, serialization error).
• Permissions Required: WriteUserMemory (either wildcard * or specific permission matching the key).

runModel(modelId: string, input: any): Promise<ModelResult>

• Purpose: Executes a specified AI model available within the Proxly platform, providing it with input data.
• Parameters:
  • modelId: string: The identifier for the AI model to use (e.g., "local-summarizer", "phi3-mini-cloud").
  • input: any: The input data for the model (must be JSON-serializable).
• Returns: A promise resolving to a ModelResult object:
  • success: boolean: Indicates if the model execution was successful.
  • output?: any: The output generated by the model.
  • error?: string: An error message if execution failed (e.g., permission denied, model unavailable, runtime error).
• Permissions Required: RunModel (either wildcard * or specific permission matching the modelId).

Types

The SDK also exports the necessary TypeScript interfaces (AppInfo, PermissionResult, MemoryReadResult, MemoryWriteResult, ModelResult, Permission). Refer to the source code (./src/types.ts) for detailed definitions.

Usage Example (React)

import React, { useState, useEffect } from 'react';
import {
  getAppInfo,
  requestPermission,
  getUserMemory,
  setUserMemory,
  runModel,
  AppInfo,
  PermissionResult,
  // ... other types
} from '@proxly/sdk';

function MyProxlyApp() {
  const [info, setInfo] = useState<AppInfo | null>(null);
  const [memoryData, setMemoryData] = useState<any>(null);

  useEffect(() => {
    // Get app info on mount
    getAppInfo().then(setInfo).catch(console.error);
  }, []);

  const handleSaveSettings = async (settings: any) => {
    try {
      const permResult = await requestPermission('WriteUserMemory:app-settings');
      if (permResult.granted) {
        const writeResult = await setUserMemory('app-settings', settings);
        if (writeResult.success) {
          console.log('Settings saved successfully!');
        } else {
          console.error('Failed to save settings:', writeResult.error);
        }
      } else {
         console.warn('Permission denied to save settings.');
      }
    } catch (error) {
      console.error('Error saving settings:', error);
    }
  };

  // ... other component logic ...

  return (
    <div>
      <h1>Welcome to {info?.name || 'Proxly App'}</h1>
      {/* ... UI elements ... */}
    </div>
  );
}