clawdforge/clients/c/include/clawdforge.h

/*
 * clawdforge — C SDK
 *
 * MIT License — see CMakeLists.txt for the full text.
 *
 * A small synchronous C client for the clawdforge HTTP service.
 * The service wraps `claude -p` subprocess calls behind a
 * bearer-token-gated REST API.
 *
 * Single public header. The client struct (cf_client_t) is opaque;
 * callers only ever see a forward-declared typedef and a set of
 * functions that take it.
 *
 * Threading: cf_client_t is NOT shared across threads. Create one
 * client per thread (or guard one client with your own mutex).
 *
 * Errors are reported through a caller-provided cf_error_t out
 * parameter — never through stderr or thread-local globals. Free
 * any populated cf_error_t with cf_error_free().
 *
 * Every output struct has a matching _free() that releases its
 * heap-allocated members. Stack-allocate the struct, pass its
 * address in, free it when done.
 */

#ifndef CLAWDFORGE_H
#define CLAWDFORGE_H

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Visibility / export attribute. The shared library is built with
 * -fvisibility=hidden by default; CF_API marks the public surface so
 * those symbols stay visible. The static library and consumers use
 * the empty default. */
#if defined(_WIN32) || defined(__CYGWIN__)
#  if defined(CLAWDFORGE_BUILDING_DLL)
#    define CF_API __declspec(dllexport)
#  elif defined(CLAWDFORGE_USING_DLL)
#    define CF_API __declspec(dllimport)
#  else
#    define CF_API
#  endif
#else
#  if defined(CLAWDFORGE_BUILDING_LIB) && defined(__GNUC__)
#    define CF_API __attribute__((visibility("default")))
#  else
#    define CF_API
#  endif
#endif

/* ------------------------------------------------------------------ */
/* Versioning                                                         */
/* ------------------------------------------------------------------ */

#define CLAWDFORGE_VERSION_MAJOR 0
#define CLAWDFORGE_VERSION_MINOR 2
#define CLAWDFORGE_VERSION_PATCH 0
#define CLAWDFORGE_VERSION_STRING "0.2.0"

/* Maximum HTTP response body size accepted by the SDK. A response
 * larger than this aborts mid-transfer with CF_ERR_TRANSPORT, which
 * caps the heap a malicious or runaway server can force the client
 * to allocate. 64 MiB is comfortably larger than any expected
 * /run, /healthz, or /admin response. */
#define CF_MAX_RESPONSE_BYTES ((size_t)64 * 1024 * 1024)

/* Returns the runtime library version string ("X.Y.Z"). */
CF_API const char *cf_version(void);

/* ------------------------------------------------------------------ */
/* Status codes                                                       */
/* ------------------------------------------------------------------ */

typedef enum cf_status {
    CF_OK            = 0, /* success */
    CF_ERR_AUTH      = 1, /* 401 / 403 from server, or missing token */
    CF_ERR_API       = 2, /* server returned a structured error envelope */
    CF_ERR_TRANSPORT = 3, /* network / TLS / connection */
    CF_ERR_USAGE     = 4, /* caller passed a bad argument */
    CF_ERR_OOM       = 5, /* malloc / calloc returned NULL */
    CF_ERR_PARSE     = 6  /* server response was not the expected JSON shape */
} cf_status_t;

/* ------------------------------------------------------------------ */
/* Error type                                                         */
/* ------------------------------------------------------------------ */

/*
 * cf_error_t is filled in by every fallible function on failure.
 * On CF_OK the contents are left untouched — do not call cf_error_free
 * if the call returned CF_OK.
 *
 * Recommended pattern:
 *
 *     cf_error_t err = {0};
 *     if (cf_run(c, &req, &res, &err) != CF_OK) {
 *         fprintf(stderr, "%s\n", cf_error_message(&err));
 *         cf_error_free(&err);
 *         return 1;
 *     }
 */
typedef struct cf_error {
    cf_status_t code;
    long        http_status;   /* HTTP status code if applicable, else 0 */
    char       *message;       /* heap-allocated, NUL-terminated */
} cf_error_t;

CF_API const char *cf_error_message(const cf_error_t *err);
CF_API void        cf_error_free(cf_error_t *err);

/* Static, never-NULL human label for a status code (e.g. "CF_OK"). */
CF_API const char *cf_status_str(cf_status_t code);

/* ------------------------------------------------------------------ */
/* Client                                                             */
/* ------------------------------------------------------------------ */

/* Opaque. */
typedef struct cf_client cf_client_t;

/*
 * Construct a new client.
 *
 *   base_url:   e.g. "http://192.168.0.5:8800". A trailing slash is
 *               tolerated. Required.
 *   token:      bearer token for /run + /files. May be NULL if the
 *               caller only intends to use admin endpoints with a
 *               separately-provided admin token (see cf_client_set_admin_token).
 *
 * Returns NULL on allocation failure. cf_client_free() releases.
 */
CF_API cf_client_t *cf_client_new(const char *base_url, const char *token);

/* Optional: install or replace the admin bootstrap token used for
 * the /admin endpoints. Pass NULL to clear. */
CF_API cf_status_t cf_client_set_admin_token(cf_client_t *c, const char *admin_token);

/* Optional: set the libcurl connection + request timeout in seconds.
 * Default is 600 seconds. Setting <= 0 leaves the current value. */
CF_API void cf_client_set_timeout_secs(cf_client_t *c, long timeout_secs);

CF_API void cf_client_free(cf_client_t *c);

/* ------------------------------------------------------------------ */
/* /healthz                                                           */
/* ------------------------------------------------------------------ */

typedef struct cf_healthz {
    int   ok;                /* "ok" field */
    int   claude_present;    /* "claude_present" field */
    char *claude_version;    /* "claude_version" or NULL */
} cf_healthz_t;

CF_API cf_status_t cf_healthz(cf_client_t *c, cf_healthz_t *out, cf_error_t *err);
CF_API void        cf_healthz_free(cf_healthz_t *h);

/* ------------------------------------------------------------------ */
/* /run                                                               */
/* ------------------------------------------------------------------ */

/*
 * Request struct. Initialise with `cf_run_request_t r = {0};` and
 * populate the fields you need. Strings are caller-owned; clawdforge
 * copies them as needed.
 */
typedef struct cf_run_request {
    const char        *prompt;        /* required, non-empty */
    const char        *model;         /* optional, NULL = server default */
    const char        *system;        /* optional system prompt */
    const char *const *files;         /* array of file_token strings */
    size_t             files_count;
    int                timeout_secs;  /* 0 = server default; else 5..600 */
} cf_run_request_t;

/*
 * Response from a successful /run call.
 *
 *   result_json:  the inner "result" field re-serialised back to a
 *                 JSON string. Always non-NULL on CF_OK. If the server
 *                 returned a string, this is a JSON-encoded string
 *                 (including the surrounding quotes); if it returned
 *                 an object, this is the object as JSON.
 *
 *   result_is_string: 1 iff the server's "result" was a JSON string;
 *                     0 if it was an object/array/number/bool/null.
 *
 *   stop_reason:  e.g. "end_turn"; may be NULL.
 *
 *   duration_ms:  server-reported duration in ms.
 */
typedef struct cf_run_result {
    char *result_json;
    int   result_is_string;
    char *stop_reason;
    long  duration_ms;
} cf_run_result_t;

CF_API cf_status_t cf_run(cf_client_t            *c,
                          const cf_run_request_t *req,
                          cf_run_result_t        *out,
                          cf_error_t             *err);
CF_API void        cf_run_result_free(cf_run_result_t *r);

/*
 * Convenience: parse out->result_json with cJSON. Returns NULL if
 * the result was not valid JSON (shouldn't happen in normal use,
 * but defensive). The caller must cJSON_Delete() the returned node.
 *
 * The return type is `void *` so the public header does not have
 * to expose the cJSON struct. Callers including cJSON.h can cast
 * directly to `cJSON *`.
 */
CF_API void *cf_run_result_as_cjson(const cf_run_result_t *r);

/* ------------------------------------------------------------------ */
/* /files                                                             */
/* ------------------------------------------------------------------ */

typedef struct cf_file_token {
    char *file_token;        /* "ff_..." */
    long  ttl_secs;
    long  size;
} cf_file_token_t;

/*
 * Upload a file from disk via multipart/form-data. The file is
 * streamed (not buffered into memory).
 *
 *   path:       absolute or relative filesystem path; must be readable.
 *   ttl_secs:   60..86400; 0 selects the server default (3600).
 */
CF_API cf_status_t cf_upload_file(cf_client_t     *c,
                                  const char      *path,
                                  long             ttl_secs,
                                  cf_file_token_t *out,
                                  cf_error_t      *err);
CF_API void        cf_file_token_free(cf_file_token_t *ft);

/* ------------------------------------------------------------------ */
/* /admin/tokens                                                      */
/* ------------------------------------------------------------------ */

typedef struct cf_admin_token {
    char  *name;
    char  *token;            /* plaintext, only present on create */
    char **ip_cidrs;
    size_t ip_cidrs_count;
} cf_admin_token_t;

typedef struct cf_admin_token_info {
    char  *name;
    char **ip_cidrs;
    size_t ip_cidrs_count;
    long   created_at;       /* UNIX seconds, 0 if absent */
    long   last_used_at;     /* UNIX seconds, 0 if absent */
} cf_admin_token_info_t;

typedef struct cf_admin_token_list {
    cf_admin_token_info_t *items;
    size_t                 count;
} cf_admin_token_list_t;

/* Mint a new app token. ip_cidrs/ip_cidrs_count may be 0 to omit. */
CF_API cf_status_t cf_admin_create_token(cf_client_t        *c,
                                         const char         *name,
                                         const char *const  *ip_cidrs,
                                         size_t              ip_cidrs_count,
                                         cf_admin_token_t   *out,
                                         cf_error_t         *err);
CF_API void        cf_admin_token_free(cf_admin_token_t *t);

CF_API cf_status_t cf_admin_list_tokens(cf_client_t           *c,
                                        cf_admin_token_list_t *out,
                                        cf_error_t            *err);
CF_API void        cf_admin_token_list_free(cf_admin_token_list_t *l);

CF_API cf_status_t cf_admin_revoke_token(cf_client_t *c,
                                         const char  *name,
                                         cf_error_t  *err);

/* ------------------------------------------------------------------ */
/* /sessions  (v0.2 — multi-turn)                                      */
/* ------------------------------------------------------------------ */

/*
 * v0.2 adds multi-turn Sessions backed by the server's ACPX path.
 * The surface is purely additive — v0.1 callers (cf_run / cf_upload_file
 * / cf_admin_*) keep working unchanged.
 *
 * Lifecycle:
 *
 *     cf_client_t      *c = cf_client_new(...);
 *     cf_session_t     *s = NULL;
 *     cf_session_options_t sopts = { .agent = "claude" };
 *     cf_session_new(c, &sopts, &s, &err);
 *
 *     cf_turn_result_t *r = NULL;
 *     cf_turn_options_t topts = {0};
 *     cf_session_turn(s, "do the thing", &topts, &r, &err);
 *     printf("%s\n", cf_turn_result_text(r));   // pointer owned by r
 *     cf_turn_result_free(r);
 *
 *     cf_session_close(s, &err);                // idempotent
 *     cf_session_free(s);                       // also closes if needed
 *
 *     cf_client_free(c);
 *
 * Threading: a cf_session_t inherits the cf_client_t's threading model.
 * Don't share one across threads; one client + one session per thread,
 * or guard with your own mutex.
 *
 * Errors: every fallible call takes a cf_error_t out-param. The bearer
 * token is NEVER reflected in any error message or log output.
 */

/* Opaque. */
typedef struct cf_session cf_session_t;

typedef struct cf_session_options {
    const char *agent;        /* default "claude"; NULL = server default */
    /* Reserved for future expansion: meta_json. NULL for v0.2. */
    const char *meta_json;
} cf_session_options_t;

typedef struct cf_turn_options {
    const char *const *files;     /* nullable; array of "ff_..." tokens */
    size_t             files_count;
    int                timeout_secs;  /* 0 = use client default */
} cf_turn_options_t;

typedef struct cf_turn_event {
    char *type;                /* e.g. "text", "tool_call", "thinking" */
    char *content;             /* nullable */
    char *name;                /* nullable */
    char *args_json;           /* nullable, raw JSON */
    char *result_json;         /* nullable, raw JSON */
} cf_turn_event_t;

typedef struct cf_turn_result {
    int               ok;            /* 0 / 1 */
    char             *session_id;
    int               turn_index;
    cf_turn_event_t  *events;
    size_t            events_count;
    char             *stop_reason;   /* nullable */
    long              duration_ms;
    /* Internal: lazy cache for cf_turn_result_text. Don't touch. */
    char             *_cached_text;
} cf_turn_result_t;

typedef struct cf_session_state {
    char *session_id;
    char *agent;
    char *app_name;
    long  created_at;
    long  last_turn_at;          /* -1 if null */
    int   turn_count;
    long  closed_at;             /* -1 if null */
} cf_session_state_t;

typedef struct cf_session_list {
    cf_session_state_t *items;
    size_t              items_count;
} cf_session_list_t;

/* Construct a new session. opts may be NULL for defaults. On CF_OK,
 * *out is a fresh cf_session_t* — release with cf_session_free(). */
CF_API cf_status_t cf_session_new(cf_client_t                *c,
                                  const cf_session_options_t *opts,
                                  cf_session_t              **out,
                                  cf_error_t                 *err);

/* Run a single turn. opts may be NULL for defaults. On CF_OK, *out is
 * a fresh cf_turn_result_t* — release with cf_turn_result_free().
 * Calling after cf_session_close returns CF_ERR_USAGE. */
CF_API cf_status_t cf_session_turn(cf_session_t            *s,
                                   const char              *prompt,
                                   const cf_turn_options_t *opts,
                                   cf_turn_result_t       **out,
                                   cf_error_t              *err);

/* Idempotent close. The first successful call issues DELETE /sessions/{id};
 * subsequent calls short-circuit and return CF_OK with no HTTP traffic. */
CF_API cf_status_t cf_session_close(cf_session_t *s, cf_error_t *err);

/* Read-only accessors into the session handle. Strings live as long as
 * the session; do not free. */
CF_API const char *cf_session_id(const cf_session_t *s);
CF_API const char *cf_session_agent(const cf_session_t *s);

/* Releases. Implicitly closes if the session is still open and the
 * caller never called cf_session_close. Safe to pass NULL. */
CF_API void        cf_session_free(cf_session_t *s);

/* Server lookups (per-token). */
CF_API cf_status_t cf_session_state_get(cf_client_t         *c,
                                        const char          *session_id,
                                        cf_session_state_t **out,
                                        cf_error_t          *err);

CF_API cf_status_t cf_session_list_get(cf_client_t        *c,
                                       cf_session_list_t **out,
                                       cf_error_t         *err);

/* Concatenate every event with type=="text" into a single string.
 * Returns a pointer OWNED by the result — caller must NOT free.
 * Computed lazily on first call. Returns "" if no text events. */
CF_API const char *cf_turn_result_text(cf_turn_result_t *r);

CF_API void cf_turn_result_free(cf_turn_result_t *r);
CF_API void cf_session_state_free(cf_session_state_t *s);
CF_API void cf_session_list_free(cf_session_list_t *l);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* CLAWDFORGE_H */