Prism Advertising SDK Development

Expert development workflow for the Prism SDK, a TypeScript client that connects publishers with the Prism protocol's real-time auction system for onchain advertising.

Architecture Understanding

Before making any changes, understand the core architecture:

1. **Single Client Class Pattern**: `PrismClient` in `src/index.ts` provides all SDK functionality via static methods

2. **Dual API Communication**:

- AWS Nitro Enclave at `prism-enclave.xyz` for privacy-preserving auctions

- Standard API at Railway deployment for tracking

3. **Browser-First Design**: Uses Web Crypto API for RSA-OAEP address encryption

4. **Zero-State Design**: All methods are static with no instance state

5. **Auto-Initialization System**: Handles both connected and unconnected wallet states

Development Workflow

1. Initial Setup and Context Gathering

When starting work:

```bash

Install dependencies

pnpm install

Review existing code structure

Read src/index.ts

Read src/config.json

Read package.json

```

2. Making Code Changes

**For new SDK methods:**

1. Add static method to `PrismClient` class in `src/index.ts`

2. Follow the established error handling pattern:

```typescript

public static async newMethod(params..., options?: ConfigOptions) {

try {

const result = await this.withRetry(async () => {

return this.fetchData(source, endpoint, jwt, body, options);

}, options?.retries);

options?.onSuccess?.(result);

return result;

} catch (error) {

const err = error instanceof Error ? error : new Error(String(error));

options?.onError?.(err);

throw err;

}

}

```

3. Update TypeScript interfaces if adding new configuration options

4. Support optional retry logic and timeout configuration

**For API endpoint changes:**

**For encryption/security changes:**

3. Testing Requirements

All changes must include comprehensive tests:

1. Run existing tests first:

```bash

npm test

```

2. Add tests following existing patterns in test files:

- Mock browser APIs (`window.crypto.subtle`, `atob`, `btoa`)

- Test both success and error scenarios

- Verify retry logic with exponential backoff

- Test timeout handling

- Validate callback execution

- Ensure mock isolation

3. Run tests in watch mode during development:

```bash

npm run test:watch

```

4. Use test UI for debugging:

```bash

npm run test:ui

```

4. Type Checking

Before committing changes:

```bash

npm run typecheck

```

Fix all TypeScript errors. The SDK must maintain strict type safety.

5. Building

Test production build:

```bash

npm run build

```

Verify output in `dist/`:

6. Local Testing with Test Client

Test integration:

```bash

npm run test:client

```

This runs the test client with tsx for end-to-end validation.

Key Implementation Patterns

Auto-Initialization Pattern

For methods supporting unconnected wallets:

```typescript

public static async autoMethod(params..., options?: ConfigOptions) {

const address = params.userAddress || '0x0000000000000000000000000000000000000000';

// Continue with auction logic

}

```

Retry Logic Pattern

Use `withRetry()` for all network calls:

```typescript

const result = await this.withRetry(async () => {

return this.fetchData(source, endpoint, jwt, body, options);

}, options?.retries || 3);

```

Callback Pattern

Support success/error callbacks:

```typescript

options?.onSuccess?.(result);

// or

options?.onError?.(err);

```

Critical Constraints

1. **Browser-Only**: Never add Node.js-specific APIs without polyfills

2. **Zero-State**: Never add instance variables to `PrismClient`

3. **Hardcoded Public Key**: Do not modify encryption public key without protocol team approval

4. **Contract Address**: `0xF2720929421eEFa11dBe627d818A9D0E68372f08` is immutable

5. **Dual API**: Maintain separation between Enclave (auctions) and API (tracking)

Common Tasks

**Add tracking method:**

1. Add static method to `PrismClient`

2. Call `fetchData()` with `'api'` source

3. Require JWT token parameter

4. Add retry logic and callbacks

5. Write tests mocking fetch responses

**Update auction logic:**

1. Modify methods in `src/index.ts:239-275`

2. Maintain address encryption flow

3. Preserve Nitro Enclave communication

4. Test with both connected and unconnected addresses

**Change API endpoints:**

1. Update `src/config.json`

2. Run full test suite

3. Test with `npm run test:client`

File Structure Reference

Error Handling Checklist

For all new methods, ensure:

Pre-Commit Checklist

Before committing changes: