### Setup WingsClient Layer with Effect-TS

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

Demonstrates how to set up the WingsClient layer for interacting with the Wings server. It shows two methods: direct configuration and environment-based configuration using Effect's Config. The client manages connections and provides access to data and control plane operations.

```typescript
import { Effect, Layer } from "effect";
import { WingsClient } from "@useairfoil/wings";

// Create a WingsClient layer with direct configuration
const wingsLayer = WingsClient.layer({
  host: "localhost:7777",
  namespace: "tenants/default/namespaces/default",
});

// Or create with environment-based configuration
import { Config } from "effect";

const wingsLayerFromEnv = WingsClient.layerConfig({
  host: Config.string("WINGS_HOST").pipe(Config.withDefault("localhost:7777")),
  namespace: Config.string("WINGS_NAMESPACE").pipe(
    Config.withDefault("tenants/default/namespaces/default")
  ),
});

// Use the layer in an Effect program
const program = Effect.gen(function* () {
  // Access cluster metadata service
  const cm = yield* WingsClient.clusterMetadata();

  // List all topics
  const { topics } = yield* cm.listTopics({
    parent: "tenants/default/namespaces/default",
  });

  console.log("Available topics:", topics.map(t => t.name));
});

// Run the program with the layer
Effect.runPromise(program.pipe(Effect.provide(wingsLayer)));
```

--------------------------------

### Manage Airfoil Clusters and Execute SQL Queries via CLI

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

Provides essential Airfoil CLI commands for installing the CLI, executing SQL queries directly or from files, and managing cluster resources like tenants, namespaces, topics, object stores, and data lakes. It covers creation, listing, retrieval, and deletion operations for these resources.

```bash
# Install CLI
bun install -g airfoil

# SQL query execution
airfoil sql "SELECT * FROM events LIMIT 10" --host localhost --port 7777
airfoil sql --file query.sql --namespace tenants/prod/namespaces/main --json

# Tenant management
airfoil cluster create-tenant --tenant-id my-tenant
airfoil cluster list-tenants
airfoil cluster get-tenant --name tenants/my-tenant
airfoil cluster delete-tenant --name tenants/my-tenant

# Namespace management
airfoil cluster create-namespace \
  --parent tenants/my-tenant \
  --namespace-id production \
  --flush-size 10485760 \
  --flush-interval 60000

airfoil cluster list-namespaces --parent tenants/my-tenant

# Topic management
airfoil cluster create-topic \
  --parent tenants/my-tenant/namespaces/production \
  --topic-id events \
  --fields '[{"name":"data","dataType":"Utf8","nullable":false}]'

airfoil cluster list-topics --parent tenants/my-tenant/namespaces/production
airfoil cluster get-topic --name tenants/my-tenant/namespaces/production/topics/events
airfoil cluster delete-topic --name tenants/my-tenant/namespaces/production/topics/events --force

# Object store management
airfoil cluster create-object-store-s3 \
  --parent tenants/my-tenant \
  --object-store-id s3-bucket \
  --bucket my-bucket \
  --region us-east-1

airfoil cluster list-object-stores --parent tenants/my-tenant

# Data lake management
airfoil cluster create-data-lake-iceberg \
  --parent tenants/my-tenant \
  --data-lake-id my-lake \
  --warehouse s3://my-bucket/warehouse

airfoil cluster list-data-lakes --parent tenants/my-tenant
```

--------------------------------

### Publish Data with Publisher in TypeScript

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

Demonstrates publishing data using the Publisher interface. It shows how to get topic metadata, create a publisher, construct an Apache Arrow RecordBatch, and push the data. Supports concurrent pushes and automatic request correlation.

```typescript
import { Effect } from "effect";
import { Int32, Utf8, makeData, RecordBatch } from "apache-arrow";
import { WingsClient, PV } from "@useairfoil/wings";

const publishData = Effect.gen(function* () {
  const cm = yield* WingsClient.clusterMetadata();

  // Get or create topic
  const topic = yield* cm.getTopic({
    name: "tenants/default/namespaces/default/topics/events",
  });

  // Create a publisher for the topic
  const publisher = yield* WingsClient.publisher({ topic });

  // Create a RecordBatch with your data
  const batch = new RecordBatch({
    user_id: makeData({
      type: new Utf8(),
      data: ["user_1", "user_2", "user_3"],
    }),
    event_type: makeData({
      type: new Utf8(),
      data: ["click", "view", "purchase"],
    }),
  });

  // Push data and await confirmation
  const result = yield* publisher.push({ batch });

  console.log("Published batch:", {
    startOffset: result.result?.accepted?.startOffset,
    endOffset: result.result?.accepted?.endOffset,
  });
  // Output: Published batch: { startOffset: 0n, endOffset: 3n }
});

// Publishing with partition values
const publishPartitioned = Effect.gen(function* () {
  const cm = yield* WingsClient.clusterMetadata();
  const topic = yield* cm.getTopic({
    name: "tenants/default/namespaces/default/topics/user_events",
  });

  const publisher = yield* WingsClient.publisher({ topic });

  const batch = new RecordBatch({
    event_data: makeData({
      type: new Utf8(),
      data: ["event1", "event2"],
    }),
  });

  // Push with explicit partition value
  const result = yield* publisher.push({
    batch,
    partitionValue: PV.int32(1000), // Partition by user_id = 1000
  });

  return result;
});

// Concurrent publishing
const publishConcurrently = Effect.gen(function* () {
  const cm = yield* WingsClient.clusterMetadata();
  const topic = yield* cm.getTopic({
    name: "tenants/default/namespaces/default/topics/events",
  });

  const publisher = yield* WingsClient.publisher({ topic });

  const batches = Array.from({ length: 10 }, (_, i) =>
    new RecordBatch({
      user_id: makeData({ type: new Utf8(), data: [`batch_${i}`] }),
    })
  );

  // Push all batches concurrently
  const results = yield* Effect.all(
    batches.map((batch) => publisher.push({ batch })),
    { concurrency: "unbounded" }
  );

  console.log(`Published ${results.length} batches`);
});

```

--------------------------------

### Interact with Arrow Flight Protocol using TypeScript

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

Provides low-level access to the Arrow Flight protocol for custom data streaming operations. It uses the '@useairfoil/flight' package and 'nice-grpc'. This client allows getting flight info, executing it to retrieve data in batches, and performing direct GET requests with a ticket.

```typescript
import { ArrowFlightClient, FlightDescriptor, FlightDescriptor_DescriptorType } from "@useairfoil/flight";
import { Metadata } from "nice-grpc";

// Create a Flight client
const flightClient = new ArrowFlightClient(
  { host: "localhost:7777" },
  {
    defaultCallOptions: {
      "*": {
        metadata: Metadata({
          "x-wings-namespace": "tenants/default/namespaces/default",
        }),
      },
    },
  }
);

// Get flight info for a topic
const descriptor = FlightDescriptor.create({
  type: FlightDescriptor_DescriptorType.PATH,
  path: ["tenants/default/namespaces/default/topics/events"],
});

const flightInfo = await flightClient.getFlightInfo(descriptor);
console.log("Endpoints:", flightInfo.endpoint.length);

// Execute flight info to get data
const batches: RecordBatch[] = [];
for await (const batch of flightClient.executeFlightInfo(flightInfo)) {
  batches.push(batch);
}

// Direct doGet with ticket
for await (const batch of flightClient.doGet(ticket, { schema: expectedSchema })) {
  console.log(`Received batch with ${batch.numRows} rows`);
}
```

--------------------------------

### Create Topics with Schema and Compaction using Effect-TS

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

Illustrates how to create topics with defined schemas, including data types, nullability, and optional partition keys. It also shows how to configure compaction settings for data freshness and time-to-live (TTL).

```typescript
import { Effect } from "effect";
import { WingsClient } from "@useairfoil/wings";

const createTopic = Effect.gen(function* () {
  const cm = yield* WingsClient.clusterMetadata();

  // Create a topic with a simple schema
  const topic = yield* cm.createTopic({
    parent: "tenants/default/namespaces/default",
    topicId: "events",
    fields: [
      { name: "user_id", dataType: "Utf8", nullable: false },
      { name: "event_type", dataType: "Utf8", nullable: false },
      { name: "timestamp", dataType: "TimestampMillisecond", nullable: false },
      { name: "payload", dataType: "Utf8", nullable: true },
    ],
    compaction: {
      freshnessSeconds: BigInt(3600), // 1 hour
      ttlSeconds: BigInt(86400 * 7),  // 7 days retention
    },
  });

  console.log("Created topic:", topic.name);
  // Output: Created topic: tenants/default/namespaces/default/topics/events

  return topic;
});

// Create a partitioned topic
const createPartitionedTopic = Effect.gen(function* () {
  const cm = yield* WingsClient.clusterMetadata();

  const topic = yield* cm.createTopic({
    parent: "tenants/default/namespaces/default",
    topicId: "user_events",
    fields: [
      { name: "event_data", dataType: "Utf8", nullable: false },
      { name: "user_id", dataType: "Int32", nullable: false }, // Partition key field
    ],
    partitionKey: 1, // Index of the partition key field (user_id)
    compaction: {
      freshnessSeconds: BigInt(1000),
      ttlSeconds: undefined,
    },
  });

  return topic;
});
```

--------------------------------

### Create Type-Safe Partition Values with TypeScript SDK

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

Demonstrates how to create type-safe partition values for various data types (integers, unsigned integers, strings, bytes, booleans, null) using the PV helper from the @useairfoil/wings SDK. It also shows how to use these partition values when publishing data.

```typescript
import { PV } from "@useairfoil/wings";

// Integer partition values
const int8Val = PV.int8(127);
const int16Val = PV.int16(32000);
const int32Val = PV.int32(2147483647);
const int64Val = PV.int64(BigInt("9223372036854775807"));

// Unsigned integers
const uint8Val = PV.uint8(255);
const uint16Val = PV.uint16(65535);
const uint32Val = PV.uint32(4294967295);
const uint64Val = PV.uint64(BigInt("18446744073709551615"));

// String and bytes
const stringVal = PV.stringValue("partition_key_value");
const bytesVal = PV.bytesValue(new Uint8Array([0x01, 0x02, 0x03]));

// Boolean and null
const boolVal = PV.boolValue(true);
const nullVal = PV.null();

// Use in publisher
const publisher = yield* WingsClient.publisher({
  topic,
  partitionValue: PV.stringValue("region-us-east"), // Default partition
});

// Override per-push
yield* publisher.push({
  batch,
  partitionValue: PV.stringValue("region-eu-west"),
});
```

--------------------------------

### Fetch Data Streams in TypeScript

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

Demonstrates fetching data streams using the fetch API. It shows how to create a stream from a topic, process RecordBatches, and handle different fetching strategies like specific partitions and timeouts. Data is returned as an Effect Stream.

```typescript
import { Effect, Stream } from "effect";
import { WingsClient, recordBatchToTable, arrowTableToRowColumns } from "@useairfoil/wings";

const fetchData = Effect.gen(function* () {
  const cm = yield* WingsClient.clusterMetadata();
  const topic = yield* cm.getTopic({
    name: "tenants/default/namespaces/default/topics/events",
  });

  // Create a fetch stream
  const stream = yield* WingsClient.fetch({
    topic,
    offset: 0n,         // Start from beginning
    minBatchSize: 1,    // Minimum records per batch
    maxBatchSize: 100,  // Maximum records per batch
  });

  // Take first 10 batches and collect
  const batches = yield* stream.pipe(
    Stream.take(10),
    Stream.runCollect
  );

  // Convert to table for easy access
  const table = recordBatchToTable(Array.from(batches));
  const { columns, rows } = arrowTableToRowColumns(table);

  console.log("Columns:", columns);
  // Output: Columns: [{ name: "user_id", type: "Utf8" }, { name: "__offset__", type: "Uint64" }]

  console.log("First row:", rows[0]);
  // Output: First row: { user_id: "user_1", __offset__: 0n, __timestamp__: ... }
});

// Fetch with partition value
const fetchPartitioned = Effect.gen(function* () {
  const cm = yield* WingsClient.clusterMetadata();
  const topic = yield* cm.getTopic({
    name: "tenants/default/namespaces/default/topics/user_events",
  });

  const stream = yield* WingsClient.fetch({
    topic,
    partitionValue: PV.int32(1000), // Fetch only user_id = 1000 partition
  });

  // Process stream continuously with logging
  yield* stream.pipe(
    Stream.tap((batch) =>
      Effect.log(`Received ${batch.numRows} rows`)
    ),
    Stream.take(5),
    Stream.runDrain
  );
});

// Run fetch with timeout
const fetchWithTimeout = Effect.gen(function* () {
  const cm = yield* WingsClient.clusterMetadata();
  const topic = yield* cm.getTopic({
    name: "tenants/default/namespaces/default/topics/events",
  });

  const stream = yield* WingsClient.fetch({ topic });

  // Collect data with 5 second timeout
  const batches = yield* stream.pipe(
    Stream.runCollect,
    Effect.timeout("5 seconds")
  );
});

```

--------------------------------

### Execute SQL Queries over Arrow Flight with TypeScript

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

Enables SQL query execution over Arrow Flight for analytical queries. This client, from '@useairfoil/flight', allows running SQL queries, fetching results in batches, and retrieving database metadata like catalogs, schemas, and tables. It also uses 'nice-grpc' for metadata handling.

```typescript
import { ArrowFlightSqlClient } from "@useairfoil/flight";
import { Metadata } from "nice-grpc";

const sqlClient = new ArrowFlightSqlClient(
  { host: "localhost:7777" },
  {
    defaultCallOptions: {
      "*": {
        metadata: Metadata({
          "x-wings-namespace": "tenants/default/namespaces/default",
        }),
      },
    },
  }
);

// Execute a SQL query
const flightInfo = await sqlClient.executeQuery({
  query: "SELECT user_id, COUNT(*) as event_count FROM events GROUP BY user_id",
});

// Fetch results
const results: any[] = [];
for await (const batch of sqlClient.executeFlightInfo(flightInfo)) {
  results.push(...batch.toArray());
}

console.log("Query results:", results);
// Output: Query results: [{ user_id: "user_1", event_count: 42 }, ...]

// Get database metadata
const catalogs = await sqlClient.getCatalogs({});
const schemas = await sqlClient.getDbSchemas({ catalog: "default" });
const tables = await sqlClient.getTables({
  catalog: "default",
  dbSchemaFilterPattern: "public",
  includeSchema: true,
});

console.log("Available tables:", tables);
```

--------------------------------

### Fetching Data Streams

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

The fetch API provides streaming data retrieval with automatic offset tracking. Data is returned as Apache Arrow RecordBatches which can be processed as an Effect Stream.

```APIDOC
## GET /fetch

### Description
Fetches data streams from a specified topic. Data is returned as Apache Arrow RecordBatches and can be processed as an Effect Stream. Supports automatic offset tracking and various filtering options.

### Method
GET

### Endpoint
/fetch

### Parameters
#### Query Parameters
- **topic** (Topic) - Required - The topic from which to fetch data.
- **offset** (bigint) - Optional - The starting offset for fetching data. Defaults to the beginning of the topic if not specified.
- **minBatchSize** (number) - Optional - The minimum number of records to include in each batch.
- **maxBatchSize** (number) - Optional - The maximum number of records to include in each batch.
- **partitionValue** (PV) - Optional - Specifies a partition to filter the fetched data.

### Request Example
```json
{
  "topic": {
    "name": "tenants/default/namespaces/default/topics/events"
  },
  "offset": "0",
  "minBatchSize": 1,
  "maxBatchSize": 100,
  "partitionValue": "PV.int32(1000)"
}
```

### Response
#### Success Response (200)
- **stream** (Stream<RecordBatch>) - An Effect Stream that yields Apache Arrow RecordBatches.

#### Response Example (Processing Stream)
```typescript
const stream = yield* WingsClient.fetch({
  topic,
  offset: 0n,
  minBatchSize: 1,
  maxBatchSize: 100,
});

const batches = yield* stream.pipe(
  Stream.take(10),
  Stream.runCollect
);

const table = recordBatchToTable(Array.from(batches));
const { columns, rows } = arrowTableToRowColumns(table);

console.log("Columns:", columns);
console.log("First row:", rows[0]);
```

### Fetching with Partition Value
Allows fetching data only from a specific partition.

### Request Example (Partitioned Fetch)
```typescript
const stream = yield* WingsClient.fetch({
  topic,
  partitionValue: PV.int32(1000), // Fetch only user_id = 1000 partition
});

yield* stream.pipe(
  Stream.tap((batch) => Effect.log(`Received ${batch.numRows} rows`)),
  Stream.take(5),
  Stream.runDrain
);
```

### Fetch with Timeout
Allows setting a timeout for the data fetching operation.

### Request Example (Fetch with Timeout)
```typescript
const stream = yield* WingsClient.fetch({ topic });

const batches = yield* stream.pipe(
  Stream.runCollect,
  Effect.timeout("5 seconds")
);
```
```

--------------------------------

### Arrow Flight SQL Client API

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

Enables SQL query execution over Arrow Flight for analytical queries on your data.

```APIDOC
## Arrow Flight SQL Client

### Description
Allows executing SQL queries against data sources accessible via Arrow Flight, and retrieving database metadata.

### Method
POST (for queries), GET (for metadata)

### Endpoint
`[host]:[port]` (e.g., `localhost:7777`)

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
(For `executeQuery`, contains the SQL query string)

### Request Example
```typescript
import { ArrowFlightSqlClient } from "@useairfoil/flight";
import { Metadata } from "nice-grpc";

const sqlClient = new ArrowFlightSqlClient(
  { host: "localhost:7777" },
  {
    defaultCallOptions: {
      "*": {
        metadata: Metadata({
          "x-wings-namespace": "tenants/default/namespaces/default",
        }),
      },
    },
  }
);

// Execute a SQL query
const flightInfo = await sqlClient.executeQuery({
  query: "SELECT user_id, COUNT(*) as event_count FROM events GROUP BY user_id",
});

// Fetch results
const results: any[] = [];
for await (const batch of sqlClient.executeFlightInfo(flightInfo)) {
  results.push(...batch.toArray());
}
console.log("Query results:", results);

// Get database metadata
const catalogs = await sqlClient.getCatalogs({});
const schemas = await sqlClient.getDbSchemas({ catalog: "default" });
const tables = await sqlClient.getTables({
  catalog: "default",
  dbSchemaFilterPattern: "public",
  includeSchema: true,
});
console.log("Available tables:", tables);
```

### Response
#### Success Response (200)
(Returns `FlightInfo` object for query results, or metadata objects for catalog/schema/table information)

#### Response Example
```json
{
  "query_results": [
    {
      "user_id": "user_1",
      "event_count": 42
    }
  ],
  "//": "..."
}
```
```

--------------------------------

### Publishing Data with Publisher

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

The Publisher interface enables high-throughput data ingestion using Apache Arrow RecordBatch format. Publishers support concurrent pushes with automatic request correlation.

```APIDOC
## POST /publish

### Description
Publishes data in Apache Arrow RecordBatch format to a specified topic. Supports concurrent pushes and automatic request correlation.

### Method
POST

### Endpoint
/publish

### Parameters
#### Query Parameters
- **topic** (Topic) - Required - The topic to which the data will be published.
- **partitionValue** (PV) - Optional - Specifies the partition to which the data should be sent.

#### Request Body
- **batch** (RecordBatch) - Required - The Apache Arrow RecordBatch containing the data to be published.

### Request Example
```json
{
  "batch": {
    "user_id": {
      "type": "Utf8",
      "data": ["user_1", "user_2", "user_3"]
    },
    "event_type": {
      "type": "Utf8",
      "data": ["click", "view", "purchase"]
    }
  },
  "partitionValue": "PV.int32(1000)"
}
```

### Response
#### Success Response (200)
- **result** (object) - Contains details about the published batch, including start and end offsets.
  - **accepted** (object)
    - **startOffset** (bigint) - The starting offset of the accepted batch.
    - **endOffset** (bigint) - The ending offset of the accepted batch.

#### Response Example
```json
{
  "result": {
    "accepted": {
      "startOffset": "0",
      "endOffset": "3"
    }
  }
}
```

### Concurrent Publishing
Allows pushing multiple batches concurrently. The `concurrency` option can be set to "unbounded" for maximum throughput.

### Request Example (Concurrent)
```typescript
const batches = Array.from({ length: 10 }, (_, i) =>
  new RecordBatch({
    user_id: makeData({ type: new Utf8(), data: [`batch_${i}`] }),
  })
);

const results = yield* Effect.all(
  batches.map((batch) => publisher.push({ batch })),
  { concurrency: "unbounded" }
);
```
```

--------------------------------

### Manage Cluster Metadata with TypeScript SDK

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

Demonstrates CRUD operations for tenants, namespaces, topics, object stores, and data lakes using the WingsClusterMetadata service. It requires the 'effect' and '@useairfoil/wings' packages. The function creates, lists, and deletes various cluster resources.

```typescript
import { Effect } from "effect";
import { WingsClusterMetadata } from "@useairfoil/wings";

// Standalone ClusterMetadata layer (without full WingsClient)
const clusterMetadataLayer = WingsClusterMetadata.layer({
  host: "localhost:7777",
});

const manageCluster = Effect.gen(function* () {
  // Tenant operations
  const tenant = yield* WingsClusterMetadata.createTenant({
    tenantId: "my-tenant",
  });
  console.log("Created tenant:", tenant.name);
  // Output: Created tenant: tenants/my-tenant

  const { tenants } = yield* WingsClusterMetadata.listTenants({
    pageSize: 100,
  });

  // Namespace operations
  const namespace = yield* WingsClusterMetadata.createNamespace({
    parent: "tenants/my-tenant",
    namespaceId: "production",
    flushSizeBytes: BigInt(1024 * 1024 * 10), // 10MB
    flushIntervalMillis: BigInt(60000),        // 1 minute
    objectStore: "tenants/my-tenant/object-stores/s3-store",
    dataLake: "tenants/my-tenant/data-lakes/iceberg-lake",
  });

  // Object store operations
  const objectStore = yield* WingsClusterMetadata.createObjectStore({
    parent: "tenants/my-tenant",
    objectStoreId: "s3-store",
    // Configuration varies by store type (S3, Azure, GCS)
  });

  // Data lake operations
  const dataLake = yield* WingsClusterMetadata.createDataLake({
    parent: "tenants/my-tenant",
    dataLakeId: "iceberg-lake",
    // Iceberg or Parquet configuration
  });

  // Topic operations
  const topic = yield* WingsClusterMetadata.createTopic({
    parent: "tenants/my-tenant/namespaces/production",
    topicId: "metrics",
    fields: [
      { name: "metric_name", dataType: "Utf8", nullable: false },
      { name: "value", dataType: "Float64", nullable: false },
    ],
    compaction: {
      freshnessSeconds: BigInt(300),
      ttlSeconds: BigInt(86400),
    },
  });

  // List topics with pagination
  const { topics, nextPageToken } = yield* WingsClusterMetadata.listTopics({
    parent: "tenants/my-tenant/namespaces/production",
    pageSize: 50,
  });

  // Delete operations
  yield* WingsClusterMetadata.deleteTopic({
    name: "tenants/my-tenant/namespaces/production/topics/old-topic",
    force: true,
  });
}).pipe(Effect.provide(clusterMetadataLayer);
```

--------------------------------

### Implement Robust Error Handling with TypeScript SDK

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

Illustrates how to handle various error types, including generic WingsErrors and specific ClusterMetadataErrors, within Effect programs using the @useairfoil/wings SDK. It demonstrates using `Effect.catchTag` and `Match` for precise error management and fallback strategies.

```typescript
import { Effect, Match } from "effect";
import { WingsClient, WingsError, ClusterMetadataError } from "@useairfoil/wings";

const robustProgram = Effect.gen(function* () {
  const cm = yield* WingsClient.clusterMetadata();

  const topic = yield* cm.getTopic({
    name: "tenants/default/namespaces/default/topics/events",
  });

  const publisher = yield* WingsClient.publisher({ topic });

  yield* publisher.push({
    batch,
  }).pipe(
    Effect.catchTag("WingsError", (error) =>
      Effect.gen(function* () {
        console.error("Push failed:", error.message);
        // Retry logic, fallback, or re-throw
        return yield* Effect.fail(error);
      })
    )
  );
}).pipe(
  Effect.catchTag("ClusterMetadataError", (error) =>
    Effect.gen(function* () {
      console.error("Metadata operation failed:", error.message);
      // Handle gRPC errors (connection issues, not found, etc.)
      return yield* Effect.fail(error);
    })
  ),
  Effect.catchAll((error) =>
    Effect.sync(() => {
      console.error("Unexpected error:", error);
    })
  )
);

// Pattern matching on errors
const handleErrors = (error: WingsError | ClusterMetadataError) =>
  Match.value(error).pipe(
    Match.tag("WingsError", (e) => `Data plane error: ${e.message}`),
    Match.tag("ClusterMetadataError", (e) => `Control plane error: ${e.message}`),
    Match.exhaustive
  );

```

--------------------------------

### Arrow Flight Client API

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

Provides low-level access to the Arrow Flight protocol for custom data streaming operations.

```APIDOC
## Arrow Flight Client

### Description
Enables direct interaction with the Arrow Flight protocol for efficient data streaming and retrieval.

### Method
GET, POST (for executeFlightInfo)

### Endpoint
`[host]:[port]` (e.g., `localhost:7777`)

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
(For `executeFlightInfo` and `doGet`, typically a `FlightDescriptor` or `Ticket`)

### Request Example
```typescript
import { ArrowFlightClient, FlightDescriptor, FlightDescriptor_DescriptorType } from "@useairfoil/flight";
import { Metadata } from "nice-grpc";

const flightClient = new ArrowFlightClient(
  { host: "localhost:7777" },
  {
    defaultCallOptions: {
      "*": {
        metadata: Metadata({
          "x-wings-namespace": "tenants/default/namespaces/default",
        }),
      },
    },
  }
);

const descriptor = FlightDescriptor.create({
  type: FlightDescriptor_DescriptorType.PATH,
  path: ["tenants/default/namespaces/default/topics/events"],
});

const flightInfo = await flightClient.getFlightInfo(descriptor);
console.log("Endpoints:", flightInfo.endpoint.length);

for await (const batch of flightClient.executeFlightInfo(flightInfo)) {
  console.log(`Received batch with ${batch.numRows} rows`);
}

// Direct doGet with ticket
// Assuming 'ticket' and 'expectedSchema' are defined elsewhere
// for await (const batch of flightClient.doGet(ticket, { schema: expectedSchema })) {
//   console.log(`Received batch with ${batch.numRows} rows`);
// }
```

### Response
#### Success Response (200)
(Returns `FlightInfo` object containing endpoints, or data batches streamed over time)

#### Response Example
```json
{
  "endpoint": [
    {
      "location": {
        "uri": "grpc://localhost:7777"
      },
      "ticket": {
        "ticket": "..."
      },
      "//": "..."
    }
  ],
  "//": "..."
}
```
```

--------------------------------

### Cluster Metadata Management API

Source: https://context7.com/useairfoil/typescript-sdk/llms.txt

Provides CRUD operations for tenants, namespaces, topics, object stores, and data lakes within the Useairfoil cluster.

```APIDOC
## Cluster Metadata Management

### Description
Manages cluster resources including tenants, namespaces, topics, object stores, and data lakes.

### Method
Various (POST, GET, DELETE)

### Endpoint
`/useairfoil/typescript-sdk` (Conceptual - operations are client-side)

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
(Varies by operation, e.g., tenantId, namespaceId, topic fields, etc.)

### Request Example
```typescript
import { Effect } from "effect";
import { WingsClusterMetadata } from "@useairfoil/wings";

const clusterMetadataLayer = WingsClusterMetadata.layer({
  host: "localhost:7777",
});

const manageCluster = Effect.gen(function* () {
  // Tenant operations
  const tenant = yield* WingsClusterMetadata.createTenant({
    tenantId: "my-tenant",
  });
  console.log("Created tenant:", tenant.name);

  // Namespace operations
  const namespace = yield* WingsClusterMetadata.createNamespace({
    parent: "tenants/my-tenant",
    namespaceId: "production",
    flushSizeBytes: BigInt(1024 * 1024 * 10), // 10MB
    flushIntervalMillis: BigInt(60000),        // 1 minute
    objectStore: "tenants/my-tenant/object-stores/s3-store",
    dataLake: "tenants/my-tenant/data-lakes/iceberg-lake",
  });

  // Topic operations
  const topic = yield* WingsClusterMetadata.createTopic({
    parent: "tenants/my-tenant/namespaces/production",
    topicId: "metrics",
    fields: [
      { name: "metric_name", dataType: "Utf8", nullable: false },
      { name: "value", dataType: "Float64", nullable: false },
    ],
    compaction: {
      freshnessSeconds: BigInt(300),
      ttlSeconds: BigInt(86400),
    },
  });

  // Delete operations
  yield* WingsClusterMetadata.deleteTopic({
    name: "tenants/my-tenant/namespaces/production/topics/old-topic",
    force: true,
  });
}).pipe(Effect.provide(clusterMetadataLayer);
```

### Response
#### Success Response (200)
(Varies by operation, returns created/updated resource or confirmation)

#### Response Example
```json
{
  "name": "tenants/my-tenant"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.