diff --git a/README.md b/README.md index d74a4cc..5a70818 100644 --- a/README.md +++ b/README.md @@ -38,10 +38,12 @@ Provides the following packages: dotnet add package Notion.Net ``` -**Note:** default Notion-Version used by NuGet package versions +**Note:** Default Notion-Version used by NuGet package versions | Package version | Notion-Version | | --- | --- | -| 4.0.0-preview-1.8.21.2022 | 2022-06-28 | +| 4.4.0+ | 2022-06-28 | +| 4.3.0+ | 2022-06-28 | +| 4.0.0+ | 2022-06-28 | | 3.0.0+ | 2022-02-22 | | 2.0.0+ | 2021-08-16 | | 1.0.0+ | 2021-05-13 | @@ -67,14 +69,33 @@ var usersList = await client.Users.ListAsync(); ## Dependency Injection -Library also provides extension method to register NotionClient with Microsoft dependency injection. +The library provides an extension method to register NotionClient with Microsoft dependency injection. -``` +```csharp services.AddNotionClient(options => { options.AuthToken = ""; }); ``` +Then inject `INotionClient` into your services: + +```csharp +public class MyService +{ + private readonly INotionClient _notionClient; + + public MyService(INotionClient notionClient) + { + _notionClient = notionClient; + } + + public async Task GetDatabaseAsync(string databaseId) + { + return await _notionClient.Databases.RetrieveAsync(databaseId); + } +} +``` + ### Querying a database After you initialized your client and got an id of a database, you can query it for any contained pages. You can add filters and sorts to your request. Here is a simple example: @@ -109,30 +130,42 @@ var complexFiler = new CompoundFilter( ## Supported Endpoints -- [x] Databases +- [x] **Authentication** + - [x] Create access token + - [x] Revoke access token + - [x] Introspect token (get token status and details) + - [x] Refresh access token +- [x] **Databases** + - [x] Retrieve a database - [x] Query a database - [x] Create a database - - [x] Update database - - [x] Retrieve a database -- [x] Pages + - [x] Update a database +- [x] **Pages** - [x] Retrieve a page - [x] Create a page - - [x] Update page + - [x] Update page properties - [x] Retrieve page property item -- [x] Blocks +- [x] **Blocks** - [x] Retrieve a block - [x] Update a block - [x] Retrieve block children - [x] Append block children - [x] Delete a block -- [x] Comments +- [x] **Comments** - [x] Retrieve comments - [x] Create comment -- [x] Users - - [x] Retrieve a User +- [x] **Users** + - [x] Retrieve a user - [x] List all users - - [x] Retrieve your token's bot user -- [x] Search + - [x] Retrieve your token's bot user (me) +- [x] **Search** + - [x] Search across pages and databases +- [x] **File Uploads** + - [x] Create file upload + - [x] Send file upload + - [x] Complete file upload (for multi-part uploads) + - [x] List file uploads + - [x] Retrieve file upload ## Enable internal logs The library make use of `ILoggerFactory` interface exposed by `Microsoft.Extensions.Logging`. Which allow you to have ability to enable the internal logs when developing application to get additional information. @@ -156,7 +189,102 @@ You can set the LogLevel in config file. } ``` -You can also refer `examples/list-users` example. +You can also refer to the `examples/list-users` example. + +## Error Handling + +The SDK provides specific exception types for common API errors: + +```csharp +try +{ + var page = await client.Pages.RetrieveAsync(pageId); +} +catch (NotionApiRateLimitException rateLimitEx) +{ + // Handle rate limit - check rateLimitEx.RetryAfter for when to retry + Console.WriteLine($"Rate limited. Retry after: {rateLimitEx.RetryAfter}"); +} +catch (NotionApiException apiEx) +{ + // Handle other API errors + Console.WriteLine($"API Error: {apiEx.NotionAPIErrorCode} - {apiEx.Message}"); +} +``` + +## Examples + +The repository includes several example projects to help you get started: + +- **[`examples/list-users`](examples/list-users/)** - Basic example showing how to list users and configure logging +- **[`examples/aspnet-core-app`](examples/aspnet-core-app/)** - ASP.NET Core integration example with dependency injection +- **[`examples/print-database-property-name-and-values`](examples/print-database-property-name-and-values/)** - Working with database properties + +## More Code Examples + +### Creating a Page +```csharp +var newPage = await client.Pages.CreateAsync(new PagesCreateParameters +{ + Parent = new DatabaseParentInput { DatabaseId = databaseId }, + Properties = new Dictionary + { + { + "Title", new TitlePropertyValue + { + Title = new List + { + new RichTextText { Text = new Text { Content = "My New Page" } } + } + } + } + } +}); +``` + +### Working with Blocks +```csharp +// Append a paragraph block to a page +var appendResponse = await client.Blocks.AppendChildrenAsync(new BlockAppendChildrenRequest +{ + BlockId = pageId, + Children = new List + { + new ParagraphBlock + { + Paragraph = new ParagraphBlock.ParagraphData + { + RichText = new List + { + new RichTextText + { + Text = new Text { Content = "This is a new paragraph!" } + } + } + } + } + } +}); +``` + +### File Upload +```csharp +// Create file upload +var fileUpload = await client.FileUploads.CreateAsync(new CreateFileUploadRequest +{ + Name = "example.pdf", + FileType = FileType.Pdf, + FileSize = fileSize, + ExpiresTime = DateTime.UtcNow.AddHours(1) +}); + +// Send the file +var sendResponse = await client.FileUploads.SendAsync(new SendFileUploadRequest +{ + FileUploadId = fileUpload.Id, + FileContent = fileBytes +}); +``` ## Contributors This project exists thanks to all the people who contribute. diff --git a/Src/Notion.Client/Notion.Client.csproj b/Src/Notion.Client/Notion.Client.csproj index 2a6555c..389eba5 100644 --- a/Src/Notion.Client/Notion.Client.csproj +++ b/Src/Notion.Client/Notion.Client.csproj @@ -1,7 +1,7 @@ - 4.3.0-preview + 4.4.0-preview netstandard2.0 9.0