/* 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 */