{
  "openapi": "3.1.0",
  "info": {
    "title": "Khang Baby LIVE KPI Workers API",
    "version": "2.0.0",
    "description": "Admin API for TikTok Shop LIVE, orders, Affiliate reconciliation, token connections, and storage usage.",
    "license": {
      "name": "Proprietary",
      "identifier": "LicenseRef-Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://sellerkhangbaby.online"
    }
  ],
  "externalDocs": {
    "description": "Agent and developer documentation",
    "url": "https://sellerkhangbaby.online/docs"
  },
  "security": [
    {
      "googleOAuth": [
        "openid",
        "email"
      ]
    },
    {
      "firebaseIdToken": []
    }
  ],
  "paths": {
    "/api/tiktok/status": {
      "get": {
        "operationId": "getTikTokStatus",
        "summary": "Read safe TikTok connection status",
        "description": "Required business permission: kpi.read.",
        "security": [
          {
            "googleOAuth": [
              "openid",
              "email"
            ]
          },
          {
            "firebaseIdToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Connection status without tokens.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Bearer token missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "Verified Admin account required.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/storage/usage": {
      "get": {
        "operationId": "getStorageUsage",
        "summary": "Read GitHub, Firebase, and Cloudflare usage",
        "description": "Required business permission: kpi.read.",
        "security": [
          {
            "googleOAuth": [
              "openid",
              "email"
            ]
          },
          {
            "firebaseIdToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Provider usage snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Bearer token missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "Verified Admin account required.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/storage/settings": {
      "post": {
        "operationId": "saveStorageSettings",
        "summary": "Save protected retention and automatic cleanup settings",
        "description": "Required business permission: kpi.connections.manage.",
        "security": [
          {
            "googleOAuth": [
              "openid",
              "email"
            ]
          },
          {
            "firebaseIdToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "retentionDays",
                  "threshold",
                  "autoFree"
                ],
                "properties": {
                  "retentionDays": {
                    "type": "integer",
                    "minimum": 60,
                    "maximum": 180
                  },
                  "threshold": {
                    "type": "integer",
                    "minimum": 50,
                    "maximum": 100
                  },
                  "autoFree": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Bearer token missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "Verified Admin account required.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "description": "Must equal https://sellerkhangbaby.online.",
            "schema": {
              "type": "string",
              "const": "https://sellerkhangbaby.online"
            }
          }
        ]
      }
    },
    "/api/storage/cleanup": {
      "post": {
        "operationId": "cleanupStorage",
        "summary": "Delete selected eligible GitHub Actions technical artifacts",
        "description": "Required business permission: kpi.connections.manage.",
        "security": [
          {
            "googleOAuth": [
              "openid",
              "email"
            ]
          },
          {
            "firebaseIdToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Bearer token missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "Verified Admin account required.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "description": "Must equal https://sellerkhangbaby.online.",
            "schema": {
              "type": "string",
              "const": "https://sellerkhangbaby.online"
            }
          }
        ]
      }
    },
    "/api/tiktok/live/sync": {
      "post": {
        "operationId": "syncLiveSessions",
        "summary": "Synchronize LIVE sessions",
        "description": "Required business permission: kpi.sync.",
        "security": [
          {
            "googleOAuth": [
              "openid",
              "email"
            ]
          },
          {
            "firebaseIdToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "from",
                  "to"
                ],
                "additionalProperties": true,
                "properties": {
                  "from": {
                    "type": "string",
                    "format": "date"
                  },
                  "to": {
                    "type": "string",
                    "format": "date"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Bearer token missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "Verified Admin account required.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/tiktok/live/core-stats": {
      "post": {
        "operationId": "syncCreatorLiveStats",
        "summary": "Refresh Creator LIVE statistics",
        "description": "Required business permission: kpi.sync.",
        "security": [
          {
            "googleOAuth": [
              "openid",
              "email"
            ]
          },
          {
            "firebaseIdToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "from",
                  "to"
                ],
                "additionalProperties": true,
                "properties": {
                  "from": {
                    "type": "string",
                    "format": "date"
                  },
                  "to": {
                    "type": "string",
                    "format": "date"
                  },
                  "creator": {
                    "type": "string",
                    "enum": [
                      "shopkhangbaby",
                      "mekhangsua"
                    ]
                  },
                  "liveIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Bearer token missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "Verified Admin account required.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/tiktok/affiliate/sync": {
      "post": {
        "operationId": "syncAffiliate",
        "summary": "Synchronize Affiliate data",
        "description": "Required business permission: kpi.sync.",
        "security": [
          {
            "googleOAuth": [
              "openid",
              "email"
            ]
          },
          {
            "firebaseIdToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "from",
                  "to"
                ],
                "additionalProperties": true,
                "properties": {
                  "from": {
                    "type": "string",
                    "format": "date"
                  },
                  "to": {
                    "type": "string",
                    "format": "date"
                  },
                  "creator": {
                    "type": "string",
                    "enum": [
                      "shopkhangbaby",
                      "mekhangsua"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Bearer token missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "Verified Admin account required.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/tiktok/orders/sync": {
      "post": {
        "operationId": "syncOrders",
        "summary": "Synchronize Seller orders and returns",
        "description": "Required business permission: kpi.sync.",
        "security": [
          {
            "googleOAuth": [
              "openid",
              "email"
            ]
          },
          {
            "firebaseIdToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "from",
                  "to"
                ],
                "additionalProperties": true,
                "properties": {
                  "from": {
                    "type": "string",
                    "format": "date"
                  },
                  "to": {
                    "type": "string",
                    "format": "date"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Bearer token missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "Verified Admin account required.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/tiktok/tokens/refresh": {
      "post": {
        "operationId": "refreshTokens",
        "summary": "Refresh all TikTok connections",
        "description": "Required business permission: kpi.connections.manage.",
        "security": [
          {
            "googleOAuth": [
              "openid",
              "email"
            ]
          },
          {
            "firebaseIdToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Bearer token missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "Verified Admin account required.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "description": "Must equal https://sellerkhangbaby.online.",
            "schema": {
              "type": "string",
              "const": "https://sellerkhangbaby.online"
            }
          }
        ]
      }
    },
    "/api/tiktok/creator/{creator}/authorize": {
      "post": {
        "operationId": "authorizeCreator",
        "summary": "Start Creator OAuth authorization",
        "description": "Required business permission: kpi.connections.manage.",
        "security": [
          {
            "googleOAuth": [
              "openid",
              "email"
            ]
          },
          {
            "firebaseIdToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Bearer token missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "Verified Admin account required.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "creator",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "shopkhangbaby",
                "mekhangsua"
              ]
            }
          },
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "description": "Must equal https://sellerkhangbaby.online.",
            "schema": {
              "type": "string",
              "const": "https://sellerkhangbaby.online"
            }
          }
        ]
      }
    },
    "/api/tiktok/seller/{connection}/authorize": {
      "post": {
        "operationId": "authorizeSeller",
        "summary": "Start Seller OAuth authorization",
        "description": "Required business permission: kpi.connections.manage.",
        "security": [
          {
            "googleOAuth": [
              "openid",
              "email"
            ]
          },
          {
            "firebaseIdToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Bearer token missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "Verified Admin account required.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "connection",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "shopkhangbaby"
              ]
            }
          },
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "description": "Must equal https://sellerkhangbaby.online.",
            "schema": {
              "type": "string",
              "const": "https://sellerkhangbaby.online"
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "googleOAuth": {
        "type": "oauth2",
        "description": "Google OAuth 2.0 access token for the verified project Admin.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
            "tokenUrl": "https://oauth2.googleapis.com/token",
            "scopes": {
              "openid": "Authenticate the Google account.",
              "email": "Read the verified Google email used for the Admin allowlist."
            }
          }
        }
      },
      "firebaseIdToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Firebase ID token",
        "description": "Firebase Authentication ID token used by the existing web application."
      }
    }
  },
  "x-oauth-protected-resource": "https://sellerkhangbaby.online/.well-known/oauth-protected-resource"
}