send and send_files should be one unified execute() function

[joshuadarron]

Right now the RocketRide SDK exposes two separate functions for getting data into a pipeline:

• send_files for file buffers
• send for chat/text

On the surface that seems reasonable. Files and text are different things. But in practice this split creates a problem that I think undermines the SDK's usability at the most critical moment: the first time a developer tries to use it.

The friction

I ran into this building a pipeline that works with raw text pulled from an external source. No files involved. I just wanted to pass a string through the pipeline. But send is scoped to chat interactions and doesn't generalize, so I was left with two options: use a function that doesn't quite fit, or manufacture an in-memory file just to satisfy send_files. Both options are wrong. Neither should exist.

The deeper issue is that a developer hitting this for the first time has to stop and ask: "which one do I use?" That question should never exist. If reading a line of documentation is required to understand the difference between two functions, the API has already failed.

What the pipeline JSON tells us

Looking at the pipeline JSON structure, the contract is already there. Source nodes declare their outgoing lane types ("text", "file", etc.). That lane type is what the pipeline actually expects. It has nothing to do with whether the transport was a webhook, a file watcher, or a direct SDK call.

So the SDK already has everything it needs to know what valid input looks like. It just isn't using that information.

The proposal

A single unified invocation method (call it execute(), open to other names) that:

• Accepts anything compatible with the pipeline's source lane types
• Validates input against the lane contract, not the transport configuration
• For pipelines with multiple source nodes and mixed lane types, accepts a map of inputs modeled as a union type
• Surfaces clear errors before anything hits the server

Roughly:

// single text source pipeline
await client.execute({ text: "review this PR" });

// mixed source pipeline
await client.execute({ text: "context", files: [buffer] });

The input shape is driven entirely by what the pipeline declares. No guessing, no reading docs, no manufacturing fake files.

On validation depth

Full static type inference at .use() time would be ideal, and there's a real path there: parse the pipeline JSON client-side, extract source lane types, generate or infer the input type. Right now .use() doesn't do any of that, it just prepares the pipeline for the server request. That's a larger investment.

But that investment doesn't have to happen before the API surface changes. Even runtime validation with clear error messages is a massive improvement over the current split. The type inference layer can grow on top of that over time.

The principle behind this

Lowering barrier to entry isn't a polish concern. It's a correctness concern. An API that forces a developer to choose between two functions, where the wrong choice means redundant code or silent misuse, is an API with a bug. The fix isn't documentation. It's removing the choice entirely.

Curious whether others have hit this, and whether there are pipeline structures I'm not accounting for where the split actually makes sense to preserve.

[github-actions[bot]]

[github-actions[bot]]

[github-actions[bot]]

[github-actions[bot]]

[github-actions[bot]]