[Release] v4.0.1

.github/workflows/check-buildstatus.yml

@@ -1,4 +1,4 @@
-name: Check TwitchLib.Api PR Build Status
+name: Check TwitchLib.Client PR Build Status
 
 on:
   pull_request:
@@ -10,12 +10,14 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v5
     - name: Setup .NET
-      uses: actions/setup-dotnet@v2
+      uses: actions/setup-dotnet@v5
       with:
-        dotnet-version: 6.0.x
+        dotnet-version: 10.0.x
     - name: Restore dependencies
       run: dotnet restore
-    - name: Build TwitchLib.Api
+    - name: Build TwitchLib.Client
       run: dotnet build --no-restore
+    - name: Test TwitchLib.Client
+      run: dotnet test --no-build --verbosity normal

.github/workflows/preview-release.yml

@@ -8,21 +8,31 @@ jobs:
   release-preview:
    if: "! contains(toJSON(github.event.commits.*.message), '[skip-ci]')"
    runs-on: ubuntu-latest
+   permissions:
+      id-token: write  # enable GitHub OIDC token issuance for this job
 
    steps:
-   - uses: actions/checkout@v3
+   - uses: actions/checkout@v5
+   - uses: benjlevesque/short-sha@v3.0
+     id: short-sha
    - name: Setup .NET
-     uses: actions/setup-dotnet@v2
+     uses: actions/setup-dotnet@v5
      with:
-       dotnet-version: 6.0.x
+       dotnet-version: 10.0.x
    - name: Restore dependencies
      run: dotnet restore
    - name: Build TwitchLib.Client
      run: dotnet build -c Release --no-restore
    - name: Pack TwitchLib.Client
-     run: dotnet pack TwitchLib.Client.sln -v normal -c Release -o nugets --no-build --version-suffix "preview-${{ github.sha }}"
+     run: dotnet pack -v normal -c Release --no-build --version-suffix "preview.${{ github.run_number }}.${{ steps.short-sha.outputs.sha }}"
+   # Get a short-lived NuGet API key
+   - name: NuGet login (OIDC → temp API key)
+     uses: NuGet/login@v1
+     id: login
+     with:
+       user: ${{ secrets.NUGET_USER }}
    - name: Push to Nuget
-     run: dotnet nuget push "./nugets/*.nupkg" -k ${{ secrets.API_NUGET_TOKEN }} -s https://api.nuget.org/v3/index.json
+     run: dotnet nuget push "./artifacts/package/release/*.nupkg" --api-key ${{steps.login.outputs.NUGET_API_KEY}} -s https://api.nuget.org/v3/index.json
    - name: Send Discord Notification
      uses: sarisia/actions-status-discord@v1
      if: always()

.github/workflows/release.yml

@@ -8,26 +8,34 @@ jobs:
   release:
    if: "contains(toJSON(github.event.commits.*.message), '[Release]')"
    runs-on: ubuntu-latest
-
+   permissions:
+      id-token: write  # enable GitHub OIDC token issuance for this job
+
    steps:
-   - uses: actions/checkout@v3
+   - uses: actions/checkout@v5
    - name: Setup .NET
-     uses: actions/setup-dotnet@v2
+     uses: actions/setup-dotnet@v5
      with:
-       dotnet-version: 6.0.x
+       dotnet-version: 10.0.x
    - name: Restore dependencies
      run: dotnet restore
    - name: Build TwitchLib.Client
      run: dotnet build -c Release --no-restore
    - name: Pack TwitchLib.Client
-     run: dotnet pack TwitchLib.Client.sln -v normal -c Release -o nugets --no-build
+     run: dotnet pack -v normal -c Release --no-build
+   # Get a short-lived NuGet API key
+   - name: NuGet login (OIDC → temp API key)
+     uses: NuGet/login@v1
+     id: login
+     with:
+       user: ${{ secrets.NUGET_USER }}     
    - name: Push to Nuget
-     run: dotnet nuget push "./nugets/*.nupkg" -k ${{ secrets.API_NUGET_TOKEN }} -s https://api.nuget.org/v3/index.json
+     run: dotnet nuget push "./artifacts/package/release/*.nupkg" --api-key ${{steps.login.outputs.NUGET_API_KEY}} -s https://api.nuget.org/v3/index.json
    - name: Send Discord Notification
      uses: sarisia/actions-status-discord@v1
      if: always()
      with:
        webhook: ${{ secrets.DISCORD_WEBHOOK }}
        title: "Release Nuget Package"
        username: "TwitchLib Deploy"
-
+

.gitignore

@@ -188,6 +188,9 @@ UpgradeLog*.htm
 # Microsoft Fakes
 FakesAssemblies/
 
+# BenchmarkDotNet artifacts
+BenchmarkDotNet.Artifacts/
+
 # =========================
 # Operating System Files
 # =========================
@@ -233,4 +236,6 @@ $RECYCLE.BIN/
 *.msp
 
 # Windows shortcuts
-*.lnk
+*.lnk
+
+.idea/*

Directory.Build.props

@@ -0,0 +1,36 @@
+<Project>
+	<!-- See https://aka.ms/dotnet/msbuild/customize for more details on customizing your build -->
+
+	<PropertyGroup>
+		<ArtifactsPath>$(MSBuildThisFileDirectory)artifacts</ArtifactsPath>
+		<ImplicitUsings>enable</ImplicitUsings>
+		<Nullable>enable</Nullable>
+		<LangVersion>latest</LangVersion>
+		<Features>strict</Features>
+
+		<NeutralLanguage>en-US</NeutralLanguage>
+		<GenerateDocumentationFile>True</GenerateDocumentationFile>
+	</PropertyGroup>
+
+	<!--Package-->
+	<PropertyGroup>
+		<Authors>swiftyspiffy, Prom3theu5, Syzuna, LuckyNoS7evin</Authors>
+		<Copyright>Copyright 2025</Copyright>
+		<PackageIcon>twitchlib.png</PackageIcon>
+		<PackageProjectUrl>https://github.com/TwitchLib/TwitchLib.Client</PackageProjectUrl>
+		<RepositoryUrl>https://github.com/TwitchLib/TwitchLib.Client</RepositoryUrl>
+		<RepositoryType>Git</RepositoryType>
+		<PackageTags>twitch library irc chat c# csharp api events net</PackageTags>
+		<PackageReleaseNotes>a lot of changes</PackageReleaseNotes>
+		<VersionPrefix>4.0.1</VersionPrefix>
+		<VersionSuffix>$(VersionSuffix)</VersionSuffix>
+		<AssemblyVersion>$(VersionPrefix)</AssemblyVersion>
+		<FileVersion>$(VersionPrefix)</FileVersion>
+		<PackageLicenseExpression>MIT</PackageLicenseExpression>
+	</PropertyGroup>
+
+	<ItemGroup>
+		<None Include="..\twitchlib.png" Pack="true" PackagePath="\" />
+	</ItemGroup>
+
+</Project>

README.md

@@ -1,4 +1,83 @@
-# TwitchLib.Client
+# TwitchLib.Client
 Client component of TwitchLib.
 
-For a general overview and example, refer to https://github.com/TwitchLib/TwitchLib/blob/master/README.md
+> [!TIP]
+> With the introduction of Chat on EventSub, it is recommended to upgrade your chatbots that are using Twitch IRC to use EventSub (for reading chat messages and roomstates) and Twitch API (for sending chat messages).
+
+## Installation
+
+| NuGet            |       | [![TwitchLib.Client][1]][2]                                       |
+| :--------------- | ----: | :---------------------------------------------------------------- |
+| Package Manager  | `PM>` | `Install-Package TwitchLib.Client -Version 4.0.1`                 |
+| .NET CLI         | `>`   | `dotnet add package TwitchLib.Client --version 4.0.1`             |
+| PackageReference |       | `<PackageReference Include="TwitchLib.Client" Version="4.0.1" />` |
+| Paket CLI        | `>`   | `paket add TwitchLib.Client --version 4.0.1`                      |
+
+[1]: https://img.shields.io/nuget/v/TwitchLib.Client.svg?label=TwitchLib.Client
+[2]: https://www.nuget.org/packages/TwitchLib.Client
+
+## ⚠ Breaking Changes in Version 4.0.1 ⚠
+
+Version 4.0.1 contains breaking changes.
+- Removed obsolete methods.
+- Methods are now asynchronous. (The return value changed from `void` to `Task` and gains `Async` suffix)
+- Events are now asynchronous (return value changed from `void` to `Task`)
+- `Add/RemoveChatCommandIdentifier` methods were removed, use `ChatCommandIdentifiers` property instead (same applies to whisper) and uses `string` instead of `char`
+- `OnLog` event was removed (you can still use `ILoggerFactory` to get logs)
+- removed builders classes (removed `TwitchLib.Client.Models.Builders namespace`)
+- changed public fields to properties
+- rewritten all models in `TwitchLib.Client.Models`
+    - some props/classes can be slightly renamed
+    - some properties (`IsModerator`, `IsSubscriber`, `HasTurbo`, `IsVip`, `IsPartner`, `IsStaff`) moved to the `UserDetails` property
+
+## Minimal Setup
+Step 1: Create a new Console project
+
+Step 2: Install the `TwitchLib.Client` NuGet package. (See above on how to do that)
+
+Step 2.5: (Optional) Install the [`Microsoft.Extensions.Logging.Console`](https://www.nuget.org/packages/Microsoft.Extensions.Logging.Console) NuGet package (or some other compatible logging provider) to see logs.
+
+Step 3: Add the following code to your `Program.cs` file:
+```cs
+using Microsoft.Extensions.Logging;
+using TwitchLib.Client;
+using TwitchLib.Client.Events;
+using TwitchLib.Client.Models;
+
+// Optional logger
+var loggerFactory = LoggerFactory.Create(c => c
+    .AddConsole()
+//    .SetMinimumLevel(LogLevel.Trace) // uncomment to view raw messages received from twitch
+);
+
+var credentials = new ConnectionCredentials(); // anonymous user, add Username and OAuth token to get the ability to send messages
+var client = new TwitchClient(loggerFactory: loggerFactory);
+
+client.Initialize(credentials);
+client.OnConnected += Client_OnConnected;
+client.OnJoinedChannel += Client_OnJoinedChannel;
+client.OnMessageReceived += Client_OnMessageReceived;
+
+await client.ConnectAsync();
+await Task.Delay(Timeout.Infinite);
+
+
+async Task Client_OnConnected(object? sender, OnConnectedEventArgs e)
+{
+    await client.JoinChannelAsync("channel_name"); // replace with the channel you want to join
+}
+
+async Task Client_OnJoinedChannel(object? sender, OnJoinedChannelArgs e)
+{
+    Console.WriteLine($"Connected to {e.Channel}");
+    await client.SendMessageAsync(e.Channel, "Hey guys! I am a bot connected via TwitchLib!");
+}
+
+async Task Client_OnMessageReceived(object? sender, OnMessageReceivedArgs e)
+{
+    Console.WriteLine($"{e.ChatMessage.Username}#{e.ChatMessage.Channel}: {e.ChatMessage.Message}");
+}
+```
+Step 4: Change the `channel_name` in the `Client_OnConnected` method to the name of the channel you want to join and run the application.
+
+More complete examples can be found in the [TwitchLib.Client.Example](/TwitchLib.Client.Example/)

TwitchLib.Client.Benchmark/ChatMessage.cs

@@ -0,0 +1,22 @@
+using BenchmarkDotNet.Attributes;
+using TwitchLib.Client.Parsing;
+using TwitchLib.Client.Models;
+using TwitchLib.Client.Models.Internal;
+
+namespace TwitchLib.Client.Benchmark
+{
+    [ShortRunJob, MemoryDiagnoser]
+    public class ChatMessageBenchmark
+    {
+        private static readonly IrcMessage Message = IrcParser.ParseMessage(
+            "@badge-info=subscriber/22;badges=subscriber/3012;color=#FFFF00;display-name=FELYP8;emote-only=1;emotes=521050:0-6,8-14,16-22,24-30,32-38,40-46,48-54,56-62,64-70,72-78,80-86,88-94,96-102,104-110,148-154,156-162,164-170,172-178,180-186,188-194,196-202,204-210,212-218,220-226,228-234,236-242,244-250,252-258,260-266/302827730:112-119/302827734:121-128/302827735:130-137/302827737:139-146;first-msg=0;flags=;id=1844235a-c24e-4e18-937b-805d6601aebe;mod=0;returning-chatter=0;room-id=22484632;subscriber=1;tmi-sent-ts=1685664001040;turbo=0;user-id=162760707;user-type= :felyp8!felyp8@felyp8.tmi.twitch.tv PRIVMSG #forsen :forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE1 forsenE2 forsenE3 forsenE4 forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE");
+
+        private readonly MessageEmoteCollection ChannelEmotes = new();
+
+        [Benchmark]
+        public ChatMessage ClientScenarioCreate()
+        {
+            return new("test_name", Message, ChannelEmotes);
+        }
+    }
+}

TwitchLib.Client.Benchmark/IrcMessageHandler.cs

@@ -0,0 +1,18 @@
+using BenchmarkDotNet.Attributes;
+using TwitchLib.Client.Parsing;
+
+namespace TwitchLib.Client.Benchmark
+{
+    [MemoryDiagnoser]
+    public class IrcMessageHandlerBenchmark
+    {
+        [Benchmark]
+        public bool ParseAndCheckFailedAuth()
+        {
+            return IrcParser
+                .ParseMessage(@"@badges=subscriber/0;color=#0000FF;display-name=KittyJinxu;emotes=30259:0-6;id=1154b7c0-8923-464e-a66b-3ef55b1d4e50;login=kittyjinxu;mod=0;msg-id=ritual;msg-param-ritual-name=new_chatter;room-id=35740817;subscriber=1;system-msg=@KittyJinxu\sis\snew\shere.\sSay\shello!;tmi-sent-ts=1514387871555;turbo=0;user-id=187446639;user-type= USERNOTICE #thorlar kittyjinxu > #thorlar: HeyGuys")
+                .ToString()
+                .StartsWith(":tmi.twitch.tv NOTICE * :Login authentication failed");
+        }
+    }
+}

TwitchLib.Client.Benchmark/IrcParser.cs

@@ -0,0 +1,23 @@
+using BenchmarkDotNet.Attributes;
+using TwitchLib.Client.Parsing;
+using TwitchLib.Client.Models.Internal;
+
+namespace TwitchLib.Client.Benchmark
+{
+    [MemoryDiagnoser]
+    public class IrcParserBenchmark
+    {
+        [Params(
+            "@msg-id=host_on :tmi.twitch.tv NOTICE #burkeblack :Now hosting DjTechlive.",
+            ":blubott.tmi.twitch.tv 366 blubott #monstercat :End of /NAMES list",
+            ":jtv!jtv@jtv.tmi.twitch.tv PRIVMSG (HOSTED):(HOSTER) is now hosting you for (VIEWERS_TOTAL) viewers.",
+            "@msg-id=raid_notice_mature :tmi.twitch.tv NOTICE #swiftyspiffy :This channel is intended for mature audiences.",
+            @"@badges=subscriber/0;color=#0000FF;display-name=KittyJinxu;emotes=30259:0-6;id=1154b7c0-8923-464e-a66b-3ef55b1d4e50;login=kittyjinxu;mod=0;msg-id=ritual;msg-param-ritual-name=new_chatter;room-id=35740817;subscriber=1;system-msg=@KittyJinxu\sis\snew\shere.\sSay\shello!;tmi-sent-ts=1514387871555;turbo=0;user-id=187446639;user-type= USERNOTICE #thorlar kittyjinxu > #thorlar: HeyGuys",
+            "@badge-info=subscriber/22;badges=subscriber/3012;color=#FFFF00;display-name=FELYP8;emote-only=1;emotes=521050:0-6,8-14,16-22,24-30,32-38,40-46,48-54,56-62,64-70,72-78,80-86,88-94,96-102,104-110,148-154,156-162,164-170,172-178,180-186,188-194,196-202,204-210,212-218,220-226,228-234,236-242,244-250,252-258,260-266/302827730:112-119/302827734:121-128/302827735:130-137/302827737:139-146;first-msg=0;flags=;id=1844235a-c24e-4e18-937b-805d6601aebe;mod=0;returning-chatter=0;room-id=22484632;subscriber=1;tmi-sent-ts=1685664001040;turbo=0;user-id=162760707;user-type= :felyp8!felyp8@felyp8.tmi.twitch.tv PRIVMSG #forsen :forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE1 forsenE2 forsenE3 forsenE4 forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE forsenE"
+        )]
+        public string? Message;
+
+        [Benchmark]
+        public IrcMessage Parse() => IrcParser.ParseMessage(Message!);
+    }
+}

TwitchLib.Client.Benchmark/Program.cs

@@ -0,0 +1,5 @@
+using BenchmarkDotNet.Running;
+
+BenchmarkSwitcher
+    .FromAssembly(typeof(Program).Assembly)
+    .Run(args);

TwitchLib.Client.Benchmark/TwitchLib.Client.Benchmark.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <IsPackable>false</IsPackable>
+    <WarningsAsErrors>nullable</WarningsAsErrors>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="BenchmarkDotNet" Version="0.15.6" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\TwitchLib.Client\TwitchLib.Client.csproj" />
+  </ItemGroup>
+
+</Project>