v1 API Reference

struct DataPoint {
    int64_t timestamp;  // Unix epoch seconds
    double  avg;
    double  min;
    double  max;
    double  sum;
};
static_assert(sizeof(DataPoint) == 40);

struct Batch {
    std::vector<DataPoint> points;
    int64_t chunk_start;    // Unix epoch seconds
    int64_t chunk_end;
    bool    is_last;
};

class DDStream {
public:
    explicit DDStream(DDStreamConfig cfg);

    // Pull-based: returns next batch or nullopt when exhausted/error
    std::optional<Batch> next_batch();
    bool        has_next()         const;
    double      progress()         const;
    void        reset();
    void        cancel();
    BatchStats  last_batch_stats() const;
    std::string last_error()       const;

    // Range-for support
    Iterator begin();
    Iterator end();

    // Callback streaming
    void stream(std::function<bool(const Batch&)> callback);

    // Validate credentials (static; makes one probe request)
    static bool validate(const DDStreamConfig& cfg, std::string& out_error);
};

DDStreamConfig cfg;
// ... fill fields ...
DDStream stream(cfg);

for (const Batch& b : stream) {
    for (const DataPoint& p : b.points) {
        std::cout << p.timestamp << "  " << p.avg << "\n";
    }
}

stream.reset();
while (stream.has_next()) {
    auto batch = stream.next_batch();
    if (!batch) {
        std::cerr << "Error: " << stream.last_error() << "\n";
        break;
    }
    std::cout << batch->points.size() << " points\n";
    std::cout << "Progress: " << stream.progress() * 100 << "%\n";
}

// Handle lifecycle
DDStreamHandle* ddstream_create(const DDStreamConfig_C* cfg);
void            ddstream_destroy(DDStreamHandle* h);

// Iteration
void    ddstream_reset(DDStreamHandle* h);
void    ddstream_cancel(DDStreamHandle* h);
int32_t ddstream_has_next(DDStreamHandle* h);           // 1 or 0
double  ddstream_progress(DDStreamHandle* h);

// Returns: 1 = batch ready, 0 = done, -1 = error
int32_t ddstream_next_batch(DDStreamHandle* h,
                             const DDPoint** points_out,
                             int32_t*        count_out,
                             DDStreamBatchInfo* info_out);

// Error & stats
const char*       ddstream_last_error(DDStreamHandle* h);
DDStreamBatchInfo ddstream_last_batch_stats(DDStreamHandle* h);

// Credential probe
int32_t ddstream_validate(const DDStreamConfig_C* cfg,
                          char* err_buf, int32_t err_buf_size);

// Arrow IPC (requires DDSTREAM_ENABLE_ARROW)
int32_t ddstream_next_batch_arrow(DDStreamHandle* h,
                                  const uint8_t** ipc_buf_out,
                                  int32_t*        ipc_size_out);

typedef struct {
    int64_t timestamp;
    double  avg;
    double  min;
    double  max;
    double  sum;
} DDPoint;
// sizeof(DDPoint) == 40