@miradorlabs/parallax-web 1.0.0

package/.nvmrc

@@ -0,0 +1 @@
+22.13.0

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false
+}

package/README.md

@@ -0,0 +1,217 @@
+# Parallax Web Client SDK
+
+Web browser SDK for the Parallax tracing platform. This package provides a browser-compatible client using gRPC-Web to interact with the Parallax Gateway API.
+
+## Installation
+
+```bash
+npm install @miradorlabs/parallax-web
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { ParallaxClient } from '@miradorlabs/parallax-web';
+
+// Initialize the client with your API key
+const client = new ParallaxClient('your-api-key');
+
+// Or with a custom gateway URL
+const client = new ParallaxClient('your-api-key', 'https://your-gateway.example.com:50053');
+```
+
+### Creating a Trace
+
+```typescript
+const traceResponse = await client.createTrace({
+  name: 'My Application Trace',
+  attributes: {
+    'project.id': 'my-project',
+    'environment': 'production',
+  },
+  tags: ['web', 'user-action'],
+});
+
+const traceId = traceResponse.traceId;
+```
+
+### Starting a Span
+
+```typescript
+const spanResponse = await client.startSpan({
+  name: 'User Login',
+  traceId: traceId,
+  attributes: {
+    'user.id': 'user-123',
+    'action': 'login',
+  },
+});
+
+const spanId = spanResponse.spanId;
+```
+
+### Adding Span Attributes
+
+```typescript
+await client.addSpanAttributes({
+  traceId: traceId,
+  spanId: spanId,
+  attributes: {
+    'response.status': '200',
+    'response.time': '145ms',
+  },
+});
+```
+
+### Adding Span Events
+
+```typescript
+await client.addSpanEvent({
+  traceId: traceId,
+  spanId: spanId,
+  eventName: 'User Authenticated',
+  attributes: {
+    'auth.method': 'oauth',
+    'auth.provider': 'google',
+  },
+});
+```
+
+### Adding Span Errors
+
+```typescript
+await client.addSpanError({
+  traceId: traceId,
+  spanId: spanId,
+  errorType: 'ValidationError',
+  message: 'Invalid email format',
+  stackTrace: error.stack,
+  attributes: {
+    'error.field': 'email',
+  },
+});
+```
+
+### Adding Span Hints (Blockchain Transactions)
+
+```typescript
+await client.addSpanHint({
+  traceId: traceId,
+  parentSpanId: spanId,
+  chainTransaction: {
+    txHash: '0x1234567890abcdef',
+    chainId: 1, // Ethereum mainnet
+  },
+});
+```
+
+### Finishing a Span
+
+```typescript
+await client.finishSpan({
+  traceId: traceId,
+  spanId: spanId,
+});
+```
+
+## Complete Example
+
+```typescript
+import { ParallaxClient } from '@miradorlabs/parallax-web';
+
+async function trackUserAction() {
+  const client = new ParallaxClient('your-api-key');
+
+  try {
+    // Create trace
+    const { traceId } = await client.createTrace({
+      name: 'User Purchase Flow',
+      attributes: { 'user.id': 'user-123' },
+      tags: ['purchase', 'web'],
+    });
+
+    // Start span
+    const { spanId } = await client.startSpan({
+      name: 'Checkout Process',
+      traceId: traceId,
+      attributes: { 'cart.items': '3' },
+    });
+
+    // Add event
+    await client.addSpanEvent({
+      traceId: traceId,
+      spanId: spanId,
+      eventName: 'Payment Initiated',
+      attributes: { 'payment.method': 'card' },
+    });
+
+    // Finish span
+    await client.finishSpan({
+      traceId: traceId,
+      spanId: spanId,
+    });
+  } catch (error) {
+    console.error('Tracing error:', error);
+  }
+}
+```
+
+## Browser Compatibility
+
+This SDK uses the Fetch API and is compatible with modern browsers that support:
+- ES2020
+- Fetch API
+- Promises
+- Uint8Array
+
+For older browsers, you may need polyfills.
+
+## Module Formats
+
+The package provides multiple module formats:
+
+- **ESM** (`dist/index.esm.js`): For modern bundlers (Webpack, Vite, etc.)
+- **UMD** (`dist/index.umd.js`): For browser globals and older module systems
+- **TypeScript** (`dist/index.d.ts`): Type definitions
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm test
+npm run test:watch
+npm run test:coverage
+```
+
+### Linting
+
+```bash
+npm run lint
+npm run format
+```
+
+## Differences from Node.js Client
+
+The web client differs from `@miradorlabs/parallax` (Node.js) in the following ways:
+
+- Uses **gRPC-Web** instead of gRPC (`@grpc/grpc-js`)
+- Uses browser **Fetch API** instead of Node.js HTTP
+- Uses **https** URLs instead of insecure connections
+- Designed for browser environments (no Node.js dependencies)
+
+## License
+
+ISC
+
+## Author
+
+@mirador

package/SETUP.md

@@ -0,0 +1,220 @@
+# Web Parallax Client Setup Summary
+
+This document summarizes the complete configuration and structure of the web-parallax-client SDK.
+
+## Directory Structure
+
+```
+web-parallax-client/
+├── dist/                          # Build output (generated)
+│   ├── index.esm.js              # ES Module bundle
+│   ├── index.esm.js.map          # ESM source map
+│   ├── index.umd.js              # UMD bundle (browser global)
+│   ├── index.umd.js.map          # UMD source map
+│   └── index.d.ts                # TypeScript declarations
+├── src/
+│   ├── grpc/
+│   │   └── index.ts              # GrpcWebRpc adapter (uses Fetch API)
+│   ├── parallax/
+│   │   └── index.ts              # ParallaxClient main class
+│   └── helpers/
+│       └── index.ts              # Serialization helpers
+├── tests/
+│   └── parallax.test.ts          # Jest unit tests
+├── index.ts                       # Main entry point
+├── package.json                   # NPM package configuration
+├── tsconfig.json                  # TypeScript config (dev)
+├── tsconfig.build.json            # TypeScript config (build)
+├── rollup.config.mjs              # Rollup bundler configuration
+├── jest.config.ts                 # Jest test configuration
+├── eslint.config.js               # ESLint configuration
+├── .prettierrc                    # Prettier configuration
+├── .nvmrc                         # Node version (22.13.0)
+├── .gitignore                     # Git ignore rules
+└── README.md                      # User documentation
+```
+
+## Key Configuration Files
+
+### package.json
+
+- **Name**: `@miradorlabs/parallax-web`
+- **Main Entry Points**:
+  - `main`: `dist/index.umd.js` (UMD for Node.js/CommonJS)
+  - `module`: `dist/index.esm.js` (ES Module for bundlers)
+  - `browser`: `dist/index.umd.js` (Browser global)
+  - `types`: `dist/index.d.ts` (TypeScript definitions)
+- **Dependencies**:
+  - `google-protobuf`: ^4.0.1
+  - `mirador-gateway-parallax-web`: grpc-web package from GCS
+  - `rxjs`: ^7.8.2
+- **Scripts**:
+  - `build`: Build all bundles with Rollup
+  - `test`: Run Jest tests
+  - `test:watch`: Run Jest in watch mode
+  - `test:coverage`: Generate coverage report
+
+### rollup.config.mjs
+
+Generates three outputs:
+
+1. **ESM Bundle** (`dist/index.esm.js`)
+   - Format: ES Module
+   - For modern bundlers (Webpack, Vite, etc.)
+
+2. **UMD Bundle** (`dist/index.umd.js`)
+   - Format: UMD
+   - Global name: `ParallaxWeb`
+   - For browser `<script>` tags
+
+3. **Type Definitions** (`dist/index.d.ts`)
+   - TypeScript declarations
+
+All bundles treat external dependencies as external:
+- `google-protobuf`
+- `mirador-gateway-parallax-web/*`
+- `rxjs/*`
+
+### tsconfig.json
+
+- Target: ES2020
+- Module: ESNext (for browser)
+- Lib: ES2020, DOM, DOM.Iterable
+- Strict mode enabled
+- Module resolution: bundler
+
+### jest.config.ts
+
+- Preset: ts-jest
+- Test environment: **jsdom** (browser simulation)
+- Test match: `**/*.test.ts`
+- Coverage from `src/**/*.ts`
+
+## Key Differences from nodejs-parallax-client
+
+| Feature | nodejs-parallax-client | web-parallax-client |
+|---------|------------------------|---------------------|
+| gRPC Library | `@grpc/grpc-js` | Fetch API (gRPC-Web compatible) |
+| Transport | Native gRPC | HTTP/HTTPS with gRPC-Web protocol |
+| Environment | Node.js | Browser |
+| Module System | CommonJS | ESM + UMD |
+| Test Environment | Node | jsdom (browser) |
+| Connection | Can use insecure | Always uses HTTPS |
+| Default URL | localhost:50053 | https://gateway-parallax-dev... |
+
+## Source Files
+
+### src/grpc/index.ts - GrpcWebRpc
+
+Implements the gRPC-Web RPC adapter using browser Fetch API:
+
+- **Unary requests**: Standard HTTP POST with protobuf binary body
+- **Server streaming**: Uses ReadableStream from Response.body
+- **Headers**: Includes `Content-Type: application/grpc-web+proto`
+- **API Key**: Sent as `x-api-key` header
+- **Type casting**: `data.buffer as ArrayBuffer` for Fetch compatibility
+
+### src/parallax/index.ts - ParallaxClient
+
+Main SDK client with methods:
+- `createTrace()`: Create a new trace
+- `startSpan()`: Start a span within a trace
+- `finishSpan()`: Finish a span
+- `addSpanAttributes()`: Add attributes to a span
+- `addSpanEvent()`: Add an event to a span
+- `addSpanError()`: Add an error to a span
+- `addSpanHint()`: Add a blockchain transaction hint
+
+### tests/parallax.test.ts
+
+Comprehensive test suite covering:
+- Client instantiation
+- All SDK methods (success and error cases)
+- Integration scenarios
+- API key handling
+- Mock implementation of GrpcWebRpc
+
+## Build Process
+
+```bash
+npm run build
+```
+
+1. Clears `dist/` directory
+2. Runs Rollup with three configurations in parallel:
+   - ESM bundle with source maps
+   - UMD bundle with source maps
+   - TypeScript declarations
+
+Build warnings about `mirador-gateway-parallax-web` imports are **expected** - these are external dependencies resolved at runtime.
+
+## Testing
+
+```bash
+npm test              # Run all tests
+npm run test:watch    # Watch mode
+npm run test:coverage # Generate coverage report
+```
+
+Tests use:
+- **jsdom**: Simulates browser environment
+- **ts-jest**: TypeScript transformation
+- **Mocking**: GrpcWebRpc is mocked for unit tests
+
+## Publishing
+
+```bash
+npm run release:patch   # Bump patch version (1.0.0 -> 1.0.1)
+npm run release:minor   # Bump minor version (1.0.0 -> 1.1.0)
+npm run release:major   # Bump major version (1.0.0 -> 2.0.0)
+```
+
+Versioning automatically:
+1. Updates `package.json` version
+2. Creates git tag
+3. Pushes with `--follow-tags`
+
+## Browser Compatibility
+
+Requires modern browsers supporting:
+- ES2020 features
+- Fetch API
+- Promises
+- ReadableStream
+- Uint8Array
+
+For older browsers, polyfills may be needed.
+
+## Usage in Browser
+
+### Via NPM/Bundler (Recommended)
+
+```typescript
+import { ParallaxClient } from '@miradorlabs/parallax-web';
+
+const client = new ParallaxClient('your-api-key');
+```
+
+### Via UMD Script Tag
+
+```html
+<script src="node_modules/@miradorlabs/parallax-web/dist/index.umd.js"></script>
+<script>
+  const client = new ParallaxWeb.ParallaxClient('your-api-key');
+</script>
+```
+
+## Next Steps
+
+1. **Install dependencies**: Already done (`npm install`)
+2. **Build**: Already done (`npm run build`)
+3. **Test**: Run `npm test` to verify all tests pass
+4. **Customize**: Update `GRPC_GATEWAY_API_URL` in `src/parallax/index.ts` if needed
+5. **Publish**: When ready, use `npm run release:patch` to version and publish
+
+## Notes
+
+- The package uses the grpc-web package from GCS: `mirador-gateway-parallax-grpc-web-1.0.9.tgz`
+- Type warnings during build about missing type declarations are expected for external packages
+- All gRPC-Web requests use the browser's Fetch API, making this SDK compatible with modern web applications
+- The SDK maintains the same API surface as the Node.js client for consistency

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import * as apiGateway from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway';
+import { CreateTraceRequest, StartSpanRequest, FinishSpanRequest, AddSpanAttributesRequest, AddSpanEventRequest, AddSpanErrorRequest, AddSpanHintRequest } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway';
+import { Observable } from 'rxjs';
+
+declare class ParallaxClient {
+    apiKey?: string | undefined;
+    apiUrl: string;
+    private apiGatewayRpc;
+    constructor(apiKey?: string | undefined, apiUrl?: string);
+    /**
+     * Create a new trace
+     * @param params Parameters to create a new trace
+     * @returns Response from the create trace operation
+     */
+    createTrace(params: CreateTraceRequest): Promise<apiGateway.CreateTraceResponse>;
+    /**
+     * Start a new span within a trace
+     * @param params Parameters to start a new span
+     */
+    startSpan(params: StartSpanRequest): Promise<any>;
+    /**
+     * Finish a span within a trace
+     * @param params Parameters to finish a span
+     */
+    finishSpan(params: FinishSpanRequest): Promise<any>;
+    /**
+     * Add attributes to a span
+     * @param params Parameters to add attributes to a span
+     */
+    addSpanAttributes(params: AddSpanAttributesRequest): Promise<any>;
+    /**
+     * Add an event to a span
+     * @param params Parameters to add an event to a span
+     */
+    addSpanEvent(params: AddSpanEventRequest): Promise<any>;
+    /**
+     * Add an error to a span
+     * @param params Parameters to add an error to a span
+     */
+    addSpanError(params: AddSpanErrorRequest): Promise<any>;
+    /**
+     * Add a hint to a span
+     * @param params Parameters to add a hint to a span
+     */
+    addSpanHint(params: AddSpanHintRequest): Promise<any>;
+}
+
+interface Metadata {
+    [key: string]: string;
+}
+interface Rpc {
+    request(service: string, method: string, data: Uint8Array, metadata?: Metadata): Promise<Uint8Array>;
+    clientStreamingRequest(service: string, method: string, data: Observable<Uint8Array>): Promise<Uint8Array>;
+    serverStreamingRequest(service: string, method: string, data: Uint8Array): Observable<Uint8Array>;
+    bidirectionalStreamingRequest(service: string, method: string, data: Observable<Uint8Array>): Observable<Uint8Array>;
+}
+declare class GrpcWebRpc implements Rpc {
+    private url;
+    private apiKey?;
+    constructor(url: string, apiKey?: string);
+    request(service: string, method: string, data: Uint8Array, metadata?: Metadata): Promise<Uint8Array>;
+    clientStreamingRequest(): Promise<Uint8Array>;
+    serverStreamingRequest(service: string, method: string, data: Uint8Array): Observable<Uint8Array>;
+    bidirectionalStreamingRequest(): Observable<Uint8Array>;
+}
+
+export { GrpcWebRpc, ParallaxClient };