/* Provider usage query core - C ABI.
 *
 * The core is pure: it never opens a socket, reads a clock, or touches the
 * filesystem. The host does the I/O, so a macOS app can use NSURLSession (system
 * trust store, proxy support, HTTP/2) and hand the body back.
 *
 * Every function returns a NUL-terminated JSON string owned by the library, or
 * NULL when allocation failed. Failures are reported inside the JSON as
 * {"error":"..."} so a caller never has to distinguish "no error" from "no data".
 * Release results with usage_free.
 */
#ifndef USAGE_H
#define USAGE_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ABI version. Bumped to 4 for a limit's id, windowSeconds and scope. */
uint32_t usage_abi_version(void);

/* Release a string returned by this library. NULL is accepted. */
void usage_free(char *ptr);

/* Provider definitions: [{"provider","providerName","credentialKinds"}] */
char *usage_providers(void);

/* Opaque state owned by the host across multi-round feeds (e.g. Hyper).
 * The core owns no cross-call state; the host owns it and passes it back.
 * Pass NULL for single-round or stateless feeds.
 */
typedef struct usage_state usage_state;

usage_state *usage_state_new(void);
void usage_state_free(usage_state *state);

/* A command request is answered with the exit status and stdout. Two statuses are worth naming:
 * 127 means this host will not run commands at all (a feed may then fall back to another path),
 * 126 means the command could not be run (missing binary, failed spawn) and is an ordinary failure.
 *
 * Advance feed state.
 * Returns either:
 *   {"requests":[{"kind":"http","method","url","headers":[["k","v"]],"body"?}]}
 * or:
 *   {"requests":[{"kind":"command","command","args":[],"stdin"?,"timeoutMs"?}]}
 * or:
 *   {"report":{accountId?, email?, planType?, limits[], balance?, notes?[], error?}}
 */
char *usage_advance(usage_state *state,
                    const char *provider, size_t provider_len,
                    const char *credential_json, size_t credential_len,
                    const char *responses_json, size_t responses_len,
                    int64_t now_ms);

/* {"accountId"?: string, "email"?: string} from an OAuth access token's claims. */
char *usage_credentials_from_access_token(const char *jwt, size_t jwt_len);

#ifdef __cplusplus
}
#endif

#endif /* USAGE_H */