Integration Guide

import httpx, os

API_KEY  = os.getenv("THSKYSHIELD_API_KEY")
SITE_ID  = os.getenv("THSKYSHIELD_SITE_ID")
BASE_URL = "https://thskyshield.com/api/v1"
HEADERS  = {"Authorization": f"Bearer {API_KEY}"}

async def check_budget(user_id: str, model: str,
                        input_tokens: int, output_tokens: int):
    async with httpx.AsyncClient() as client:
        r = await client.post(f"{BASE_URL}/check", headers=HEADERS, json={
            "site_id":          SITE_ID,
            "external_user_id": user_id,
            "model":            model,
            "estimated_tokens": {"input": input_tokens, "output": output_tokens},
        })
        return r.json()

async def log_usage(request_id: str, model: str,
                    input_tokens: int, output_tokens: int):
    async with httpx.AsyncClient() as client:
        await client.post(f"{BASE_URL}/log", headers=HEADERS, json={
            "site_id":        SITE_ID,
            "request_id":     request_id,
            "model":          model,
            "actual_tokens":  {"input": input_tokens, "output": output_tokens},
            "status":         "success",
        })

# ── Usage in your FastAPI route ──────────────────────────────────────────────

@app.post("/chat")
async def chat(body: ChatRequest, user_id: str):
    check = await check_budget(user_id, "gpt-4o", 800, 300)

    if not check["allowed"]:
        raise HTTPException(status_code=429,
                            detail={"error": "Budget exceeded",
                                    "reason": check["reason"]})

    completion = await openai_client.chat.completions.create(
        model="gpt-4o", messages=body.messages
    )

    await log_usage(
        check["request_id"], "gpt-4o",
        completion.usage.prompt_tokens,
        completion.usage.completion_tokens,
    )

    return {"response": completion.choices[0].message.content}

package thskyshield

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

const baseURL = "https://thskyshield.com/api/v1"

type CheckRequest struct {
    SiteID          string          `json:"site_id"`
    ExternalUserID  string          `json:"external_user_id"`
    Model           string          `json:"model"`
    EstimatedTokens TokenEstimate   `json:"estimated_tokens"`
}

type TokenEstimate struct {
    Input  int `json:"input"`
    Output int `json:"output"`
}

type CheckResponse struct {
    Allowed         bool    `json:"allowed"`
    RequestID       string  `json:"request_id"`
    BudgetRemaining float64 `json:"budget_remaining"`
    Reason          string  `json:"reason,omitempty"`
}

func Check(userID, model string, input, output int) (*CheckResponse, error) {
    body, _ := json.Marshal(CheckRequest{
        SiteID:         os.Getenv("THSKYSHIELD_SITE_ID"),
        ExternalUserID: userID,
        Model:          model,
        EstimatedTokens: TokenEstimate{Input: input, Output: output},
    })

    req, _ := http.NewRequest("POST", baseURL+"/check", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer "+os.Getenv("THSKYSHIELD_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    resp, err := (&http.Client{}).Do(req)
    if err != nil { return nil, err }
    defer resp.Body.Close()

    var result CheckResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return &result, nil
}

require 'net/http'
require 'json'

class ThskyShield
  BASE_URL = 'https://thskyshield.com/api/v1'

  def self.check(user_id:, model:, input_tokens:, output_tokens:)
    call(:check, {
      site_id:          ENV['THSKYSHIELD_SITE_ID'],
      external_user_id: user_id,
      model:            model,
      estimated_tokens: { input: input_tokens, output: output_tokens }
    })
  end

  def self.log(request_id:, model:, input_tokens:, output_tokens:)
    call(:log, {
      site_id:       ENV['THSKYSHIELD_SITE_ID'],
      request_id:    request_id,
      model:         model,
      actual_tokens: { input: input_tokens, output: output_tokens },
      status:        'success'
    })
  end

  def self.call(endpoint, payload)
    uri = URI("#{BASE_URL}/#{endpoint}")
    req = Net::HTTP::Post.new(uri)
    req['Authorization'] = "Bearer #{ENV['THSKYSHIELD_API_KEY']}"
    req['Content-Type']  = 'application/json'
    req.body             = payload.to_json
    res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
    JSON.parse(res.body)
  end
end

# ── Usage ────────────────────────────────────────────────────────────────────

result = ThskyShield.check(user_id: current_user.id,
                            model: 'gpt-4o',
                            input_tokens: 800, output_tokens: 300)

if !result['allowed']
  render json: { error: 'Budget exceeded', reason: result['reason'] }, status: 429
  return
end

# Step 1 — check before calling your LLM
curl -X POST https://thskyshield.com/api/v1/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id":          "YOUR_SITE_ID",
    "external_user_id": "user_123",
    "model":            "gpt-4o",
    "estimated_tokens": { "input": 800, "output": 300 }
  }'

# Response (allowed):
# {
#   "allowed": true,
#   "request_id": "req_a1b2c3d4e5f6",
#   "budget_remaining": 0.34,
#   "budget_limit": 0.50,
#   "user_spend_today": 0.16
# }

# Step 2 — log actual usage after your LLM responds
curl -X POST https://thskyshield.com/api/v1/log \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id":       "YOUR_SITE_ID",
    "request_id":    "req_a1b2c3d4e5f6",
    "model":         "gpt-4o",
    "actual_tokens": { "input": 743, "output": 287 },
    "status":        "success"
  }'