{
  "openapi": "3.1.0",
  "info": {
    "title": "Bestboy Wishlists API",
    "description": "API for creating, managing, and sharing wishlists on bestboy.app. Backed by Supabase (PostgREST + Edge Functions).",
    "version": "1.0.0",
    "contact": {
      "name": "Bestboy",
      "url": "https://bestboy.app"
    }
  },
  "servers": [
    {
      "url": "https://tcwbpxdiutixaoxwqtpo.supabase.co",
      "description": "Supabase backend"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Supabase Auth JWT obtained via email/password sign-in"
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "apikey",
        "description": "Supabase anon key (required on all PostgREST requests)"
      }
    },
    "schemas": {
      "Wishlist": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "user_id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "description": { "type": "string", "nullable": true },
          "is_public": { "type": "boolean" },
          "share_link": { "type": "string", "nullable": true },
          "share_token": { "type": "string", "nullable": true },
          "sort_order": { "type": "integer", "nullable": true },
          "expires_at": { "type": "string", "format": "date-time", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "Wish": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "user_id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "description": { "type": "string", "nullable": true },
          "link": { "type": "string", "nullable": true },
          "links": { "type": "array", "items": { "type": "string" }, "nullable": true },
          "image_url": { "type": "string", "nullable": true },
          "price": { "type": "number", "nullable": true },
          "priority": { "type": "integer", "nullable": true },
          "occasion": {
            "type": "string",
            "enum": ["Birthday", "Christmas", "Vacations", "Anniversary", "Self love", "Home", "Other"]
          },
          "emoji": { "type": "string", "nullable": true },
          "received": { "type": "boolean" },
          "reserved": { "type": "boolean" },
          "reserved_at": { "type": "string", "format": "date-time", "nullable": true },
          "is_donation": { "type": "boolean" },
          "donation_type": { "type": "string", "enum": ["exact", "any"], "nullable": true },
          "donation_amount": { "type": "number", "nullable": true },
          "donation_currency": { "type": "string", "nullable": true },
          "donation_message": { "type": "string", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "Profile": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string", "nullable": true },
          "birthday": { "type": "string", "format": "date", "nullable": true },
          "hide_received_wishes": { "type": "boolean" },
          "hide_reserved_from_shared": { "type": "boolean" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "UrlMeta": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "image_url": { "type": "string", "nullable": true }
        }
      }
    }
  },
  "security": [
    { "bearerAuth": [] },
    { "apiKey": [] }
  ],
  "paths": {
    "/rest/v1/wishes_lists": {
      "get": {
        "operationId": "listWishlists",
        "summary": "List wishlists for authenticated user",
        "tags": ["Wishlists"],
        "security": [{ "bearerAuth": [], "apiKey": [] }],
        "parameters": [
          { "name": "select", "in": "query", "schema": { "type": "string" }, "example": "*" },
          { "name": "order", "in": "query", "schema": { "type": "string" }, "example": "created_at.desc" }
        ],
        "responses": {
          "200": {
            "description": "List of wishlists",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Wishlist" } }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createWishlist",
        "summary": "Create a new wishlist",
        "tags": ["Wishlists"],
        "security": [{ "bearerAuth": [], "apiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string", "maxLength": 120 },
                  "description": { "type": "string", "maxLength": 1000 }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Wishlist created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Wishlist" }
              }
            }
          }
        }
      }
    },
    "/rest/v1/wishes_lists?id=eq.{id}": {
      "get": {
        "operationId": "getWishlist",
        "summary": "Get a specific wishlist by ID",
        "tags": ["Wishlists"],
        "security": [{ "bearerAuth": [], "apiKey": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": {
          "200": {
            "description": "Wishlist details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Wishlist" }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateWishlist",
        "summary": "Update a wishlist",
        "tags": ["Wishlists"],
        "security": [{ "bearerAuth": [], "apiKey": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "description": { "type": "string" },
                  "is_public": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Wishlist updated" }
        }
      },
      "delete": {
        "operationId": "deleteWishlist",
        "summary": "Delete a wishlist",
        "tags": ["Wishlists"],
        "security": [{ "bearerAuth": [], "apiKey": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": {
          "204": { "description": "Wishlist deleted" }
        }
      }
    },
    "/rest/v1/wishes": {
      "get": {
        "operationId": "listWishes",
        "summary": "List wishes for authenticated user",
        "tags": ["Wishes"],
        "security": [{ "bearerAuth": [], "apiKey": [] }],
        "parameters": [
          { "name": "select", "in": "query", "schema": { "type": "string" } },
          { "name": "order", "in": "query", "schema": { "type": "string" }, "example": "created_at.desc" }
        ],
        "responses": {
          "200": {
            "description": "List of wishes",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Wish" } }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createWish",
        "summary": "Create a new wish",
        "tags": ["Wishes"],
        "security": [{ "bearerAuth": [], "apiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string", "maxLength": 200 },
                  "description": { "type": "string" },
                  "link": { "type": "string", "format": "uri" },
                  "price": { "type": "number", "minimum": 0 },
                  "emoji": { "type": "string" },
                  "occasion": { "type": "string", "enum": ["Birthday", "Christmas", "Vacations", "Anniversary", "Self love", "Home", "Other"] }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Wish created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Wish" }
              }
            }
          }
        }
      }
    },
    "/rest/v1/wish_lists": {
      "post": {
        "operationId": "attachWishToList",
        "summary": "Attach a wish to a wishlist",
        "tags": ["Wish-List Associations"],
        "security": [{ "bearerAuth": [], "apiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["wish_id", "list_id"],
                "properties": {
                  "wish_id": { "type": "string", "format": "uuid" },
                  "list_id": { "type": "string", "format": "uuid" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Association created" }
        }
      }
    },
    "/rest/v1/wishes_lists?share_link=eq.{shareToken}&is_public=eq.true": {
      "get": {
        "operationId": "getSharedWishlist",
        "summary": "Get a publicly shared wishlist by share token",
        "tags": ["Sharing"],
        "security": [{ "apiKey": [] }],
        "parameters": [
          { "name": "shareToken", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Public wishlist",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Wishlist" }
              }
            }
          }
        }
      }
    },
    "/functions/v1/extract-url-meta": {
      "post": {
        "operationId": "extractUrlMeta",
        "summary": "Extract title and OG image from a URL",
        "tags": ["Utilities"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": { "type": "string", "format": "uri" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted metadata",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UrlMeta" }
              }
            }
          }
        }
      }
    },
    "/functions/v1/mcp": {
      "post": {
        "operationId": "mcpServer",
        "summary": "MCP JSON-RPC 2.0 endpoint for AI agent tool calls",
        "description": "Model Context Protocol server. Supports methods: initialize, tools/list, tools/call, ping.",
        "tags": ["MCP"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["jsonrpc", "method"],
                "properties": {
                  "jsonrpc": { "type": "string", "const": "2.0" },
                  "id": { "type": ["string", "integer"] },
                  "method": { "type": "string", "enum": ["initialize", "tools/list", "tools/call", "ping"] },
                  "params": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": { "type": "string" },
                    "id": { "type": ["string", "integer", "null"] },
                    "result": { "type": "object" },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": { "type": "integer" },
                        "message": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}