<!--
hoody-pipe Subskill (sdk)
Auto-generated by Hoody Skills Generator
Generated: 2026-06-20T00:13:21.340Z
Model: mimo-v2.5-pro
Mode: sdk


Tokens: 6217

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-pipe Subskill

## Overview

### What is Hoody Pipe?

Hoody Pipe is a real-time data streaming service that enables temporary, ephemeral connections between devices. Unlike traditional storage services, Pipe does **not store data server-side** — it acts as a live conduit that directly streams data from sender to receiver(s) in real time.

**Key characteristics:**
- **Ephemeral**: Data flows through Pipe but is never persisted. When the connection ends, data is gone.
- **Real-time**: Receivers block until a sender connects, then stream directly.
- **Path-based routing**: Any string can be a "pipe path" — no pre-registration required.
- **Multi-receiver**: Multiple receivers can connect to the same path and receive the same stream.
- **Zero setup**: Pipes are created on-demand by simply connecting to a path.

### When to Use Hoody Pipe

| Use Case | Why Pipe? |
|----------|-----------|
| Transfer files between devices | No upload/download lifecycle — just stream |
| Send text/logs to another browser tab | Works across tabs, devices, networks |
| Build real-time data pipelines | Sender/receiver pattern without brokers |
| Browser-based file sharing | Built-in web UI with drag-and-drop |
| Quick data transfer in scripts | Simple curl-compatible API |

### How Pipe Fits the Hoody Philosophy

Hoody services follow a philosophy of **ephemeral, composable infrastructure**. Pipe embodies this by:

- **No persistence layer**: Zero storage costs, zero cleanup concerns
- **Instant provisioning**: Paths exist the moment you connect — no configuration
- **Protocol flexibility**: Supports browser UI, curl, and programmatic SDK access
- **Service isolation**: Each Pipe instance has its own namespace via the container routing pattern

### Service Endpoints Summary

| Endpoint | Purpose |
|----------|---------|
| `GET /api/v1/pipe` | Web UI for browser-based transfers |
| `GET /api/v1/pipe/noscript` | JavaScript-free upload form |
| `GET /api/v1/pipe/help` | Usage instructions with curl examples |
| `GET /api/v1/pipe/health` | Service health check |
| `GET /api/v1/pipe/{path}` | Receive data from a pipe |
| `POST /api/v1/pipe/{path}` | Send data to a pipe |
| `PUT /api/v1/pipe/{path}` | Send data (alias for curl -T) |
| `OPTIONS /api/v1/pipe/{path}` | CORS preflight |

---

## Common Workflows

### Workflow 1: Check Service Health

Verify the Pipe service is running before performing operations.

```
import { HoodyClient } from '@hoody-ai/hoody-sdk'

const client = new HoodyClient({
  baseURL: 'https://api.hoody.com',
  token: process.env.HOODY_TOKEN
})

const health = await client.pipe.health.check()
console.log(health)
```

```
{
  "status": "ok",
  "service": "pipe",
  "version": "1.0.0",
  "uptime": 3600,
  "timestamp": "2025-01-15T10:30:00Z",
  "node": "us-east-1",
  "projectId": "proj_abc123",
  "containerId": "cnt_xyz789",
  "serviceId": "svc_pipe_001"
}
```

### Workflow 2: Send and Receive Data Between Two Sessions

The fundamental Pipe pattern: one session sends, another receives. The receiver blocks until the sender connects.

**Step 1: Start a receiver (blocks until data arrives)**

```
import { HoodyClient } from '@hoody-ai/hoody-sdk'

const client = new HoodyClient({
  baseURL: 'https://api.hoody.com',
  token: process.env.HOODY_TOKEN
})

// This call blocks until a sender connects to "my-transfer-path"
const data = await client.pipe.receive({ path: 'my-transfer-path' })
console.log(data)
```

```
{
  "headers": {
    "content-type": "application/octet-stream"
  },
  "body": "SGVsbG8gV29ybGQ="
}
```

**Step 2: Send data to the same path (connects to waiting receiver)**

```
import { HoodyClient } from '@hoody-ai/hoody-sdk'

const client = new HoodyClient({
  baseURL: 'https://api.hoody.com',
  token: process.env.HOODY_TOKEN
})

// Sends data to receivers waiting on "my-transfer-path"
const result = await client.pipe.send({ path: 'my-transfer-path' })
console.log(result)
```

```
{
  "status": "sent",
  "path": "my-transfer-path",
  "bytesTransferred": 4096,
  "receivers": 1
}
```

**Verification**: If the receiver returns data and the sender reports `bytesTransferred > 0`, the transfer succeeded.

### Workflow 3: Transfer a File Using the Web UI

Share a file by directing another user to the Pipe web interface.

**Step 1: Get the web UI URL**

```
import { HoodyClient } from '@hoody-ai/hoody-sdk'

const client = new HoodyClient({
  baseURL: 'https://api.hoody.com',
  token: process.env.HOODY_TOKEN
})

const ui = await client.pipe.ui.getIndex()
console.log(ui)
```

```
{
  "html": "<!DOCTYPE html><html>...</html>",
  "contentType": "text/html"
}
```

**Step 2: Generate a no-script fallback link**

For environments where JavaScript is disabled:

```
const noscript = await client.pipe.ui.getNoScript('my-file-path', 'upload')
console.log(noscript)
```

```
{
  "html": "<!DOCTYPE html><html>...</html>",
  "contentType": "text/html"
}
```

### Workflow 4: Get Usage Help with Server-Specific Examples

Retrieve help text that includes the actual service URL, so examples are ready to copy-paste.

```
import { HoodyClient } from '@hoody-ai/hoody-sdk'

const client = new HoodyClient({
  baseURL: 'https://api.hoody.com',
  token: process.env.HOODY_TOKEN
})

const help = await client.pipe.info.getHelp()
console.log(help)
```

```
{
  "text": "Usage examples for sending and receiving data...",
  "contentType": "text/plain"
}
```

### Workflow 5: Receive Data with Query Parameters

Control receiver behavior using optional parameters for file downloads and progress tracking.

```
import { HoodyClient } from '@hoody-ai/hoody-sdk'

const client = new HoodyClient({
  baseURL: 'https://api.hoody.com',
  token: process.env.HOODY_TOKEN
})

const data = await client.pipe.receive(
  'download-path',
  1,
  'true',
  'report.pdf',
  'false',
  'true'
)
```

```
{
  "headers": {
    "content-type": "application/pdf",
    "content-disposition": "attachment; filename=\"report.pdf\""
  },
  "body": "JVBERi0xLjQK..."
}
```

### Workflow 6: Send Data with Receiver Count Limit

Limit how many receivers can connect to a single send operation.

```
import { HoodyClient } from '@hoody-ai/hoody-sdk'

const client = new HoodyClient({
  baseURL: 'https://api.hoody.com',
  token: process.env.HOODY_TOKEN
})

const result = await client.pipe.send('broadcast-path', 5)
```

```
{
  "status": "sent",
  "path": "broadcast-path",
  "bytesTransferred": 1024,
  "receivers": 3
}
```

---

## Advanced Operations

### Advanced Workflow 1: Bidirectional Data Pipeline

Create a request-response pattern using two pipe paths.

**Step 1: Define the pipe paths**

```
const REQUEST_PATH = 'pipeline-request'
const RESPONSE_PATH = 'pipeline-response'
```

**Step 2: Start both sender and receiver roles**

```
import { HoodyClient } from '@hoody-ai/hoody-sdk'

const client = new HoodyClient({
  baseURL: 'https://api.hoody.com',
  token: process.env.HOODY_TOKEN
})

async function startBidirectionalPipeline() {
  // Simultaneously prepare to receive on both paths
  const [requestData, responseData] = await Promise.all([
    client.pipe.receive(REQUEST_PATH),
    client.pipe.receive(RESPONSE_PATH)
  ])

  console.log('Request received:', requestData)
  console.log('Response received:', responseData)
}
```

```
{
  "requestPath": "pipeline-request",
  "responsePath": "pipeline-response",
  "status": "pipeline-ready"
}
```

**Step 3: Send data through the pipeline**

```
async function sendThroughPipeline(input: string) {
  // Send request
  await client.pipe.send(REQUEST_PATH)
  // Receive response (already blocked in step 2)
  await client.pipe.send(RESPONSE_PATH)
}
```

### Advanced Workflow 2: Handle CORS for Browser Applications

Use the OPTIONS endpoint to enable cross-origin browser access.

**Step 1: Execute CORS preflight**

```
import { HoodyClient } from '@hoody-ai/hoody-sdk'

const client = new HoodyClient({
  baseURL: 'https://api.hoody.com',
  token: process.env.HOODY_TOKEN
})

const corsHeaders = await client.pipe.corsPreflight({ path: 'browser-path' })
console.log(corsHeaders)
```

```
{
  "headers": {
    "access-control-allow-origin": "*",
    "access-control-allow-methods": "GET, POST, PUT, OPTIONS",
    "access-control-allow-headers": "Content-Type, Authorization",
    "access-control-max-age": "86400"
  }
}
```

**Step 2: Perform the actual data transfer from browser context**

```
const result = await client.pipe.send({ path: 'browser-path' })
```

```
{
  "status": "sent",
  "path": "browser-path",
  "bytesTransferred": 2048,
  "receivers": 1
}
```

### Advanced Workflow 3: Error Recovery with Retry Logic

Implement resilient pipe operations with automatic retry.

```
import { HoodyClient } from '@hoody-ai/hoody-sdk'

const client = new HoodyClient({
  baseURL: 'https://api.hoody.com',
  token: process.env.HOODY_TOKEN
})

async function sendWithRetry(
  path: string,
  maxRetries: number = 3,
  delayMs: number = 1000
): Promise<void> {
  let lastError: Error | null = null

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const result = await client.pipe.send(path)
      console.log(`Attempt ${attempt} succeeded`)
      return
    } catch (error) {
      lastError = error as Error
      console.log(`Attempt ${attempt} failed, retrying in ${delayMs}ms`)
      if (attempt < maxRetries) {
        await new Promise(resolve => setTimeout(resolve, delayMs))
      }
    }
  }

  throw new Error(`All ${maxRetries} attempts failed: ${lastError?.message}`)
}
```

```
{
  "status": "sent",
  "path": "resilient-path",
  "bytesTransferred": 512,
  "receivers": 1,
  "attempt": 2
}
```

### Performance Considerations

| Factor | Recommendation |
|--------|----------------|
| **Path naming** | Use short, unique paths to avoid collisions |
| **Receiver count** | Limit receivers with the `n` parameter for large broadcasts |
| **Connection timeouts** | Receivers block indefinitely — implement client-side timeouts |
| **Large files** | Use streaming; Pipe does not buffer server-side |
| **Concurrent pipes** | Each path is independent — many pipes can run simultaneously |
| **Network failures** | Pipe connections are not resumable — restart the full transfer |

**State verification pattern:**

```
// Verify health before starting long operations
const health = await client.pipe.health.check()
if (health.status !== 'ok') {
  throw new Error('Pipe service unavailable')
}

// Proceed with data transfer
const result = await client.pipe.send({ path: 'verified-path' })
```

---

## Quick Reference

### Most Common Endpoints

| Action | SDK Method | HTTP |
|--------|-----------|------|
| Receive data | `client.pipe.receive(path)` | `GET /api/v1/pipe/{path}` |
| Send data | `client.pipe.send(path)` | `POST /api/v1/pipe/{path}` |
| Health check | `client.pipe.health.check()` | `GET /api/v1/pipe/health` |
| Get help | `client.pipe.info.getHelp()` | `GET /api/v1/pipe/help` |
| Web UI | `client.pipe.ui.getIndex()` | `GET /api/v1/pipe` |
| No-JS UI | `client.pipe.ui.getNoScript(path?, mode?)` | `GET /api/v1/pipe/noscript` |
| CORS preflight | `client.pipe.corsPreflight(path)` | `OPTIONS /api/v1/pipe/{path}` |

### Essential Parameters

| Parameter | Endpoint | Type | Description |
|-----------|----------|------|-------------|
| `path` | receive, send, corsPreflight | string | Pipe path identifier (required) |
| `n` | receive, send | integer | Max receiver count |
| `download` | receive | string | Trigger file download |
| `filename` | receive | string | Download filename |
| `video` | receive | string | Video streaming mode |
| `progress` | receive | string | Progress reporting |

### Service URL Pattern

```
https://{projectId}-{containerId}-pipe-{serviceId}.{node}.containers.hoody.com
```

**Important**: The `{path}` parameter goes directly after `/api/v1/pipe/` — not as a query parameter. Examples:
- `GET /api/v1/pipe/my-data` — receives from path "my-data"
- `POST /api/v1/pipe/my-data` — sends to path "my-data"

### Typical Response Formats

**Health response:**

```
{
  "status": "ok",
  "service": "pipe",
  "version": "1.0.0",
  "uptime": 3600,
  "timestamp": "2025-01-15T10:30:00Z",
  "node": "us-east-1",
  "projectId": "proj_abc123",
  "containerId": "cnt_xyz789",
  "serviceId": "svc_pipe_001"
}
```

**Send response:**

```
{
  "status": "sent",
  "path": "example-path",
  "bytesTransferred": 4096,
  "receivers": 2
}
```

**Receive response:**

```
{
  "headers": {
    "content-type": "application/octet-stream"
  },
  "body": "base64-encoded-data"
}
```