Documentation

-- Basic command
client:CreateCommand("ping", function(message, args)
    message:Reply("Pong!")
end)

-- With arguments: !say hello world
client:CreateCommand("say", function(message, args)
    -- args[1] = "hello", args[2] = "world"
    -- args.raw = "hello world"
    message:Reply(args.raw)
end)

-- task.wait inside commands
client:CreateCommand("countdown", function(message, args)
    message:Reply("3...")
    silicord.task.wait(1)
    message:Reply("2...")
    silicord.task.wait(1)
    message:Reply("1... Go!")
end)

client:CreateSlashCommand("ban", {
    description = "Ban a user from the server",
    options = {
        { name = "user",   description = "The user to ban",    type = "user",   required = true  },
        { name = "reason", description = "Reason for the ban", type = "string", required = false }
    }
}, function(interaction, args)
    interaction:Reply("Banned " .. args.user .. ". Reason: " .. (args.reason or "none"))
end)

client.OnError:Connect(function(error_type, ctx, name, detail)
    if error_type == "CommandNotFound" then
        ctx:Reply("❌ Unknown command `!" .. name .. "`.")
    elseif error_type == "MissingArgument" then
        ctx:Reply("❌ Missing argument for `!" .. name .. "`.")
    elseif error_type == "CommandError" then
        ctx:Reply("❌ Something went wrong running `!" .. name .. "`.")
        print("CommandError in !" .. name .. ": " .. detail)
    elseif error_type == "SlashCommandError" then
        ctx:Reply("❌ Something went wrong running `/" .. name .. "`.")
    elseif error_type == "ComponentError" then
        print("ComponentError in " .. name .. ": " .. detail)
    elseif error_type == "UnknownInteraction" then
        ctx:Reply("❌ Unknown slash command.")
    end
end)

-- Edit the reply after a delay
client:CreateCommand("temp", function(message, args)
    local response = message:Reply("Processing...")
    silicord.task.wait(3)
    response:Edit("Done! ✅")
end)

-- Auto-delete the bot response
client:CreateCommand("autodelete", function(message, args)
    local response = message:Send("This disappears in 5 seconds.")
    silicord.task.delay(5, function()
        response:Delete()
    end)
end)

message.author.id        -- user ID
message.author.username  -- username
message.author.bot       -- true if the author is a bot

local member = message:GetMember()
local member = interaction:GetMember()
local member = guild:GetMember(user_id)

-- Raw seconds still work
member:Timeout(300, "Spamming")

-- Enum.PunishmentLength values (v1.2.0+)
member:Timeout(silicord.Enum.PunishmentLength["5Minutes"], "Spamming")
member:Timeout(silicord.Enum.PunishmentLength["1Hour"])
member:Timeout(silicord.Enum.PunishmentLength.Permanent, "Repeated violations")

-- Check member status (v1.2.0+)
local status = member:GetStatus()
if status == silicord.Enum.UserStatusInGuild.Banned then
    ctx:Reply("That user is already banned.")
end

member.id        -- user ID
member.username  -- username
member.nickname  -- server nickname (nil if not set)
member.roles     -- table of role IDs
member.user      -- raw Discord user object

local guild = message:GetGuild()
-- guild.id, guild.name

-- String names
guild:CreateChannel("general",  "text")
guild:CreateChannel("General",  "voice")
guild:CreateChannel("Info",     "category")
guild:CreateChannel("news",     "announcement")
guild:CreateChannel("Stage",    "stage")
guild:CreateChannel("help",     "forum")
guild:CreateChannel("media",    "media")

-- Enum.ChannelType values (v1.2.0+)
guild:CreateChannel("general", silicord.Enum.ChannelType.Text)
guild:CreateChannel("Music",   silicord.Enum.ChannelType.Voice)

-- With options
guild:CreateChannel("general", "text", {
    topic     = "General chat",
    parent_id = "category_channel_id",
    nsfw      = false,
    slowmode  = 5
})
guild:CreateChannel("Music", "voice", {
    bitrate    = 64000,
    user_limit = 10
})

guild:CreateEvent({
    name        = "Game Night",
    description = "Monthly game night!",
    type        = "external",   -- "stage", "voice", or "external"
    location    = "Discord Stage", -- for "external" type
    start_time  = "2025-09-01T20:00:00Z",
    end_time    = "2025-09-01T23:00:00Z"
})

guild:CreateEvent({
    name       = "Community Call",
    type       = "stage",
    channel_id = "stage_channel_id",
    start_time = "2025-09-01T20:00:00Z",
    end_time   = "2025-09-01T21:00:00Z"
})

guild:EditEvent(event_id, { name = "Updated Name" })
guild:DeleteEvent(event_id)
local events = guild:GetEvents()

local embed = silicord.Instance.new("Embed")
embed.Title       = "My Embed"
embed.Description = "This is the description."
embed.Color       = silicord.Color3.fromRGB(88, 101, 242)
embed.Url         = "https://example.com"
embed.Timestamp   = os.date("!%Y-%m-%dT%H:%M:%SZ")
embed.Author      = "Author Name"
embed.AuthorIcon  = "https://example.com/icon.png"
embed.AuthorUrl   = "https://example.com"
embed.Footer      = "Footer text"
embed.FooterIcon  = "https://example.com/icon.png"
embed.Image       = "https://example.com/image.png"
embed.Thumbnail   = "https://example.com/thumb.png"
embed:AddField("Field 1", "Value 1", true)
embed:AddField("Field 2", "Value 2", false)

message:Reply("Here is info:", embed:Build())

-- ⚠ DEPRECATED — use silicord.Instance.new("Embed") instead
local embed = silicord.Embed({
    title       = "My Embed",
    description = "This is the description.",
    color       = "#5865F2"
})
message:Reply(embed)

local c = silicord.Color3.fromRGB(88, 101, 242)
local c = silicord.Color3.fromHex("#5865F2")

-- Pass directly to any color field (v1.0.0+)
embed.Color = silicord.Color3.fromHex("#57F287")

-- Use in guild:CreateRole
guild:CreateRole("Moderator", silicord.Color3.fromRGB(255, 165, 0))

-- Get the raw integer (rarely needed)
local int = c:ToInt()

client:CreateCommand("vote", function(message, args)
    local yes = silicord.Instance.new("Button")
    yes.Label    = "Yes"
    yes.Style    = "success"
    yes.CustomId = "vote_yes"

    local no = silicord.Instance.new("Button")
    no.Label    = "No"
    no.Style    = "danger"
    no.CustomId = "vote_no"

    local row = silicord.Instance.new("ActionRow")
    row:Add(yes)
    row:Add(no)

    message:Reply("Cast your vote!", nil, { row:Build() })
end)

client:CreateComponent("vote_yes", function(interaction)
    interaction:Update("You voted Yes! ✅")
end)

client:CreateCommand("color", function(message, args)
    local menu = silicord.Instance.new("SelectMenu")
    menu.CustomId    = "color_pick"
    menu.Placeholder = "Pick a color"
    menu:AddOption("Red",   "red",   "A warm color")
    menu:AddOption("Blue",  "blue",  "A cool color")
    menu:AddOption("Green", "green", "A natural color")

    local row = silicord.Instance.new("ActionRow")
    row:Add(menu)

    message:Reply("Choose a color:", nil, { row:Build() })
end)

client:CreateComponent("color_pick", function(interaction)
    interaction:Update("You picked: **" .. interaction.values[1] .. "**")
end)

-- ⚠ DEPRECATED
local row = silicord.ActionRow(
    silicord.Button({ label = "Yes", style = "success", custom_id = "vote_yes" }),
    silicord.Button({ label = "No",  style = "danger",  custom_id = "vote_no"  })
)

local DS       = silicord:GetService("DataStoreService")
local Http     = silicord:GetService("HttpService")
local Presence = silicord:GetService("PresenceService")
local AI       = silicord:GetService("AIService")

silicord.Enum.Presence.Online        -- "online"
silicord.Enum.Presence.Idle          -- "idle"
silicord.Enum.Presence.DoNotDisturb  -- "dnd"
silicord.Enum.Presence.Invisible     -- "invisible"

silicord.Enum.ChannelType.Text         -- 0
silicord.Enum.ChannelType.DM           -- 1
silicord.Enum.ChannelType.Voice        -- 2
silicord.Enum.ChannelType.GDM          -- 3
silicord.Enum.ChannelType.Category     -- 4
silicord.Enum.ChannelType.Announcement -- 5
silicord.Enum.ChannelType.Thread       -- 11
silicord.Enum.ChannelType.Stage        -- 13
silicord.Enum.ChannelType.Forum        -- 15
silicord.Enum.ChannelType.Media        -- 16

-- Pass directly to guild:CreateChannel()
guild:CreateChannel("general", silicord.Enum.ChannelType.Text)
guild:CreateChannel("Music",   silicord.Enum.ChannelType.Voice)

silicord.Enum.Permissions.CreateInstantInvite  -- 0x1
silicord.Enum.Permissions.KickMembers          -- 0x2
silicord.Enum.Permissions.BanMembers           -- 0x4
silicord.Enum.Permissions.Administrator        -- 0x8
silicord.Enum.Permissions.ManageChannels       -- 0x10
silicord.Enum.Permissions.ManageGuild          -- 0x20
silicord.Enum.Permissions.AddReactions         -- 0x40
silicord.Enum.Permissions.ViewAuditLog         -- 0x80
silicord.Enum.Permissions.PrioritySpeaker      -- 0x100
silicord.Enum.Permissions.Stream               -- 0x200
silicord.Enum.Permissions.ReadMessages         -- 0x400
silicord.Enum.Permissions.ViewChannel          -- 0x400
silicord.Enum.Permissions.SendMessages         -- 0x800
silicord.Enum.Permissions.SendTTSMessages      -- 0x1000
silicord.Enum.Permissions.ManageMessages       -- 0x2000
silicord.Enum.Permissions.EmbedLinks           -- 0x4000
silicord.Enum.Permissions.AttachFiles          -- 0x8000
silicord.Enum.Permissions.ReadMessageHistory   -- 0x10000
silicord.Enum.Permissions.MentionEveryone      -- 0x20000
silicord.Enum.Permissions.UseExternalEmojis    -- 0x40000
silicord.Enum.Permissions.ViewGuildInsights    -- 0x80000
silicord.Enum.Permissions.Connect              -- 0x100000
silicord.Enum.Permissions.Speak                -- 0x200000
silicord.Enum.Permissions.MuteMembers          -- 0x400000
silicord.Enum.Permissions.DeafenMembers        -- 0x800000
silicord.Enum.Permissions.MoveMembers          -- 0x1000000
silicord.Enum.Permissions.UseVAD               -- 0x2000000
silicord.Enum.Permissions.ChangeNickname       -- 0x4000000
silicord.Enum.Permissions.ManageNicknames      -- 0x8000000
silicord.Enum.Permissions.ManageRoles          -- 0x10000000
silicord.Enum.Permissions.ManageWebhooks       -- 0x20000000
silicord.Enum.Permissions.ManageExpressions    -- 0x40000000

silicord.Enum.PunishmentLength["1Minute"]   -- 60
silicord.Enum.PunishmentLength["5Minutes"]  -- 300
silicord.Enum.PunishmentLength["10Minutes"] -- 600
silicord.Enum.PunishmentLength["30Minutes"] -- 1800
silicord.Enum.PunishmentLength["1Hour"]     -- 3600
silicord.Enum.PunishmentLength["6Hours"]    -- 21600
silicord.Enum.PunishmentLength["12Hours"]   -- 43200
silicord.Enum.PunishmentLength["1Day"]      -- 86400
silicord.Enum.PunishmentLength["3Days"]     -- 259200
silicord.Enum.PunishmentLength["1Week"]     -- 604800
silicord.Enum.PunishmentLength.Permanent    -- nil (no end date)

member:Timeout(silicord.Enum.PunishmentLength["30Minutes"], "Spamming")
member:Timeout(silicord.Enum.PunishmentLength.Permanent,    "Repeated violations")

silicord.Enum.UserStatusInGuild.None     -- "none"
silicord.Enum.UserStatusInGuild.TimedOut -- "timed_out"
silicord.Enum.UserStatusInGuild.Kicked   -- "kicked"
silicord.Enum.UserStatusInGuild.Banned   -- "banned"

local DS = silicord:GetService("DataStoreService")
local db = DS:GetDataStore("PlayerData")

db:SetAsync("score_user123", 500)

local score = db:GetAsync("score_user123")

local new_score = db:IncrementAsync("score_user123", 10)

db:RemoveAsync("score_user123")

local keys = db:GetKeys()
for _, k in ipairs(keys) do
    print(k, db:GetAsync(k))
end

local Http = silicord:GetService("HttpService")

-- GET request
local body, code = Http:Get("https://api.example.com/data")

-- POST request
local body, code = Http:Post("https://api.example.com/submit", '{"key":"value"}')

-- Full control
local body, code = Http:Request("https://api.example.com", "PATCH", '{"x":1}', {
    ["X-Custom-Header"] = "abc"
})

local Presence = silicord:GetService("PresenceService")

Presence:SetPresence(client, {
    presence = silicord.Enum.Presence.Online,  -- Enum.Presence value
    status   = "Watching over the server!",   -- text shown under the bot name
    type     = 3                               -- 0=Playing, 1=Streaming, 2=Listening, 3=Watching, 5=Competing
})

local AI = silicord:GetService("AIService")

AI:Configure("sk-your-api-key-here", {
    model    = "gpt-4o",                   -- default: "gpt-3.5-turbo"
    base_url = "https://api.openai.com/v1"  -- change for other providers
})

client:CreateSlashCommand("ask", {
    description = "Ask the AI a question",
    options = {
        { name = "question", description = "Your question", type = "string", required = true }
    }
}, function(interaction, args)
    local reply = AI:Prompt(args.question, "You are a helpful Discord bot assistant.")
    interaction:Reply(reply or "Sorry, I could not get a response.")
end)

-- ⚠ DEPRECATED — use DataStoreService instead
local db = silicord.DataStore("PlayerData")

db:SetAsync("score_user123", 500)
local score = db:GetAsync("score_user123")
local new_score = db:IncrementAsync("score_user123", 10)
db:RemoveAsync("score_user123")

local keys = db:GetKeys()
for _, k in ipairs(keys) do
    print(k, db:GetAsync(k))
end

-- Create a custom signal
local mySignal = silicord.Signal.new()

-- Connect a listener (returns a connection)
local conn = mySignal:Connect(function(a, b)
    print("Signal fired!", a, b)
end)

-- Fire the signal
mySignal:Fire("hello", 42)

-- Disconnect later
conn.Disconnect()

-- Yield until the signal fires (must be inside a coroutine)
silicord.task.spawn(function()
    local a, b = mySignal:Wait()
    print("Resumed with:", a, b)
end)

-- Built-in: listen to all non-command, non-bot messages
client.OnMessage:Connect(function(message)
    print(message.author.username .. ": " .. message.content)
end)

local clamped = silicord.math.clamp(150, 0, 100)   -- 100
local lerped  = silicord.math.lerp(0, 10, 0.5)     -- 5.0

local parts = silicord.string.split("a,b,c", ",")  -- {"a","b","c"}
local clean = silicord.string.trim("  hello  ")    -- "hello"

local idx  = silicord.table.find({"a","b","c"}, "b") -- 2
local copy = silicord.table.copy(someTable)

local cs = silicord.CollectionService

cs:AddTag(message.author.id, "admin")
cs:AddTag(message.author.id, "vip")

print(cs:HasTag(message.author.id, "admin"))  -- true

local admins = cs:GetTagged("admin")
local tags   = cs:GetTags(message.author.id)  -- { "admin", "vip" }

cs:RemoveTag(message.author.id, "vip")

-- Cooldown (3 seconds per user per command)
local cooldowns = {}
client:AddMiddleware(function(ctx, cmd, args)
    local key = ctx.author.id .. ":" .. cmd
    if os.time() - (cooldowns[key] or 0) < 3 then
        ctx:Reply("Slow down! Wait 3 seconds between commands.")
        return false
    end
    cooldowns[key] = os.time()
end)

-- Admin-only guard using CollectionService tags
silicord.CollectionService:AddTag(nil, "ban",  "AdminOnly")
silicord.CollectionService:AddTag(nil, "kick", "AdminOnly")

local ADMIN_ID = "123456789012345678"
client:AddMiddleware(function(ctx, cmd, args)
    if silicord.CollectionService:HasTag(nil, cmd, "AdminOnly") then
        if ctx.author.id ~= ADMIN_ID then
            ctx:Reply("You do not have permission to use this command.")
            return false
        end
    end
end)

client.cache.guilds   -- raw guild data keyed by guild ID
client.cache.users    -- raw user data keyed by user ID
client.cache.bot_user -- the bot's own user object (set after READY)

-- Pause inside any coroutine
silicord.task.wait(2)

-- Fire and forget a background thread
silicord.task.spawn(function()
    silicord.task.wait(5)
    print("5 seconds later")
end)

-- defer: runs after the current frame completes
silicord.task.defer(function()
    print("deferred to next cycle")
end)

-- delay: clean one-shot timer
silicord.task.delay(10, function()
    print("10 seconds have passed!")
end)

-- Practical: send a temp message that auto-deletes
client:CreateCommand("temp", function(message, args)
    local response = message:Reply("This disappears in 5 seconds!")
    silicord.task.delay(5, function()
        response:Delete()
    end)
end)