Widget Integration

Installation

Install the widget package:

npm install @proof-of-spend/widget
# or
bun add @proof-of-spend/widget

Basic Usage

Import and use the widget in your React application:

import { ProofOfSpendWidget } from '@proof-of-spend/widget';

function App() {
  return (
    <ProofOfSpendWidget
      apiUrl="https://your-oauth-server.com"
      onVerified={(data) => {
        console.log('Task verified:', data);
        // Handle verification data
      }}
    />
  );
}

Configuration

Props

Prop	Type	Required	Description
`apiUrl`	`string`	Yes	OAuth backend URL
`onVerified`	`(data: VerificationData) => void`	Yes	Called when task is verified
`theme`	`'light' \| 'dark'`	No	Widget theme (default: `'light'`)
`providers`	`Provider[]`	No	Available providers (default: all)
`className`	`string`	No	Custom CSS class

Provider Types

type Provider = 'openai' | 'anthropic' | 'google';

Verification Data

interface VerificationData {
  taskId: string;
  response: string;
  provider: Provider;
  cost: number;
  timestamp: string;
  proof: {
    accessToken: string;
    apiCallHash: string;
  };
}

Advanced Usage

Custom Providers

Restrict available providers:

<ProofOfSpendWidget
  apiUrl="https://your-oauth-server.com"
  providers={['openai', 'anthropic']}
  onVerified={handleVerification}
/>

Custom Styling

Apply custom styles:

<ProofOfSpendWidget
  apiUrl="https://your-oauth-server.com"
  className="my-custom-widget"
  theme="dark"
  onVerified={handleVerification}
/>

.my-custom-widget {
  max-width: 600px;
  margin: 0 auto;
  border-radius: 12px;
}

Error Handling

Handle errors gracefully:

<ProofOfSpendWidget
  apiUrl="https://your-oauth-server.com"
  onVerified={handleVerification}
  onError={(error) => {
    console.error('Widget error:', error);
    // Show user-friendly error message
  }}
/>

State Management

The widget uses an internal state machine with these states:

loading: Initial state, fetching configuration
provider-selection: User selects OAuth provider
task-ready: Task loaded and ready for user
submitting: User submitted response, calling API
verifying: Verifying API call proof
verified: Task successfully verified
error: Error occurred

Using the Hook Directly

For more control, use the useProofOfSpend hook:

import { useProofOfSpend } from '@proof-of-spend/widget';

function CustomWidget() {
  const {
    state,
    task,
    response,
    setResponse,
    selectProvider,
    submitResponse,
    reset,
  } = useProofOfSpend({
    apiUrl: 'https://your-oauth-server.com',
  });

  return (
    <div>
      {state === 'provider-selection' && (
        <button onClick={() => selectProvider('openai')}>
          Use OpenAI
        </button>
      )}
      {state === 'task-ready' && (
        <div>
          <p>{task.prompt}</p>
          <textarea
            value={response}
            onChange={(e) => setResponse(e.target.value)}
          />
          <button onClick={submitResponse}>Submit</button>
        </div>
      )}
    </div>
  );
}

Testing

The widget includes comprehensive tests:

# Run widget tests
cd proof-of-spend-widget
bun test