Feat(core) unified client api

[andrewmelchor]

Summary

Consolidate createRemoteClient into createClient with automatic server mode detection. One API for all use cases.

---

Changes

1. Test Fixture Update

File: packages/app/test/fixtures/http/run-test.ts

Remove explicit server option - rely on TREQ_SERVER env var injection:

import { createClient } from '@t-req/core';

const client = createClient({
variables: {
baseUrl: 'https://httpbin.org/',
userId: '123',
token: '1234567890'
}
});

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• [] New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring
• Chore (dependency update, build script changes, etc.)

How Has This Been Tested?

• Unit tests
• E2E tests
• Manual testing (please describe)

Checklist

• I have followed the contributing guidelines
• I have performed a self-review of my own code
• I have added tests that prove my fix is effective or that my feature works
• I have updated the documentation accordingly
• My changes generate no new warnings

[github-actions]

🚀 Preview Deployment

Your changes have been deployed to:

📖 Docs: https://docs-pr-9.t-req.io

This preview will be automatically removed when the PR is closed.

[greptile-apps]

Greptile Overview

Greptile Summary

Unifies client API by merging createRemoteClient into createClient with automatic server mode detection via server config option or TREQ_SERVER environment variable.

Key Changes:

• createClient() now routes to server-backed implementation when server option or TREQ_SERVER env var is present
• Removed createRemoteClient export - now a breaking change requiring users to migrate to unified API
• Added close() and [Symbol.asyncDispose] methods to Client interface for resource cleanup
• Server client supports TUI flow attachment via TREQ_FLOW_ID environment variable
• New getServerMetadata() utility for extracting session/flow IDs from server-backed clients
• Comprehensive test coverage for both local and server modes

Implementation Quality:

• Clean separation between local and server implementations
• Proper handling of variable synchronization with promise chaining to prevent race conditions
• Graceful handling of TUI-attached flows (doesn't finish flows it didn't create)
• Well-documented API with TypeScript examples including async disposal pattern

Confidence Score: 5/5

• Safe to merge - well-designed breaking change with proper test coverage and clear migration path
• High confidence due to: (1) comprehensive test coverage for both local and server modes, (2) clean architectural separation with proper error handling, (3) backward-compatible behavior for existing local clients, (4) well-documented breaking changes with clear migration examples in README, (5) proper resource management with close() and async disposal support
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/src/client.ts	Added automatic routing to server client when server config or TREQ_SERVER env var is set, plus close() and async dispose support
packages/core/src/index.ts	Removed createRemoteClient export, added getServerMetadata export for new unified API
packages/core/src/server-client.ts	Internal server-backed client implementation with session/flow management, variable syncing, and TUI flow attachment support
packages/core/src/types.ts	Added server, serverToken, and profile options to ClientConfig, and close() + async dispose methods to Client interface

Sequence Diagram

sequenceDiagram
    participant User
    participant createClient
    participant LocalClient
    participant ServerClient
    participant TreqServer

    User->>createClient: createClient(config)
    
    alt config.server OR TREQ_SERVER env var set
        createClient->>ServerClient: createServerClient(config)
        Note over ServerClient: Store serverUrl, token, variables
        createClient-->>User: Client (server-backed)
        
        User->>ServerClient: run() or runString()
        ServerClient->>ServerClient: ensureInitialized()
        
        alt First request (not initialized)
            ServerClient->>TreqServer: POST /session (with variables)
            TreqServer-->>ServerClient: sessionId
            
            alt No TREQ_FLOW_ID env var
                ServerClient->>TreqServer: POST /flows (with sessionId)
                TreqServer-->>ServerClient: flowId
            else TREQ_FLOW_ID set (TUI mode)
                Note over ServerClient: Use existing flowId from env
            end
        end
        
        ServerClient->>ServerClient: await variableSyncChain
        ServerClient->>TreqServer: POST /execute (sessionId, flowId, content/path)
        TreqServer-->>ServerClient: ExecuteResponse
        ServerClient-->>User: Response
        
        User->>ServerClient: close()
        alt Flow was created by client
            ServerClient->>TreqServer: POST /flows/{flowId}/finish
        else Flow was attached (TUI mode)
            Note over ServerClient: Skip finish (TUI manages flow)
        end
    else No server config
        createClient->>LocalClient: Create local client
        Note over LocalClient: Initialize engine with config
        createClient-->>User: Client (local)
        
        User->>LocalClient: run() or runString()
        LocalClient->>LocalClient: engine.runFile/runString()
        LocalClient-->>User: Response
        
        User->>LocalClient: close()
        Note over LocalClient: No-op (no resources to release)
    end

Loading