notionapi Go Client

In the notionapi library, all Notion blocks implement the Block interface. This allows you to work with a collection of heterogeneous blocks (a Blocks slice) and use type assertions or the interface methods to access specific data.

Common interface methods:

• GetType() BlockType: Returns the specific type of the block (e.g., paragraph, heading_1, to_do).
• GetID() BlockID: Returns the unique identifier.
• GetRichTextString() string: A helper method that returns the plain text content of the block (concatenating rich text where applicable).

func processBlocks(blocks notion.Blocks) {
    for _, b := range blocks {
        fmt.Printf("Block ID: %s, Type: %s, Text: %s\n", 
            b.GetID(), 
            b.GetType(), 
            b.GetRichTextString(),
        )

        // Type assertion to access specific block properties
        if todo, ok := b.(*notion.ToDoBlock); ok {
            fmt.Printf("Is Checked: %v\n", todo.ToDo.Checked)
        }
    }
}

The NewClient constructor accepts functional options to override default settings. Use these to customize the HTTP client, API version, retry logic, or OAuth credentials.

Available options:

• WithHTTPClient(client *http.Client): Overrides the default http.Client.
• WithVersion(version string): Overrides the Notion-Version header (defaults to 2022-06-28).
• WithRetry(retries int): Overrides the number of retry attempts for 429 Too Many Requests errors (defaults to 3).
• WithOAuthAppCredentials(id, secret string): Sets the OAuth app ID and secret used for Basic authentication when fetching tokens.

import (
	"net/http"
	"github.com/jomei/jomei/notionapi"
)

client := notionapi.NewClient(
	notionapi.Token("your_token"),
	notionapi.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
	notionapi.WithVersion("2022-06-28"),
	notionapi.WithRetry(5),
	notionapi.WithOAuthAppCredentials("client_id", "client_secret"),
)

The BlockService interface provides methods to interact with Notion blocks. You can use a BlockClient to implement this service for retrieving, updating, appending, or deleting blocks.

Key operations include:

• Get(ctx, id): Retrieves a single block by its BlockID.
• GetChildren(ctx, id, pagination): Returns a paginated list of child blocks for a specific block.
• AppendChildren(ctx, id, request): Appends new blocks as children to a parent block. Note that blocks appended via this method cannot be moved elsewhere via the API.
• Update(ctx, id, request): Updates the content of an existing block. The update replaces the entire value for a given field; omitting a field leaves its current value unchanged.
• Delete(ctx, id): Archives a block (moves it to the Trash).

// Example usage of BlockService methods
// Assuming 'client' is an initialized *BlockClient

// 1. Get a block
block, err := client.Get(ctx, notion.BlockID("block_id"))

// 2. Append children
appendReq := &notion.AppendBlockChildrenRequest{
    Children: notion.Blocks{
        &notion.ParagraphBlock{
            BasicBlock: notion.BasicBlock{Type: notion.BlockTypeParagraph},
            Paragraph: notion.Paragraph{RichText: []notion.RichText{{PlainText: "Hello World"}}},
        },
    },
}
client.AppendChildren(ctx, notion.BlockID("parent_id"), appendReq)

// 3. Update a block
updateReq := &notion.BlockUpdateRequest{
    ToDo: &notion.ToDo{
        RichText: []notion.RichText{{PlainText: "Updated Task"}},
        Checked:  true,
    },
}
client.Update(ctx, notion.BlockID("todo_id"), updateReq)

The PropertyConfigs type is a map of string to PropertyConfig. It implements a custom UnmarshalJSON method that automatically detects the property type from the JSON payload and instantiates the correct concrete struct (e.g., TitlePropertyConfig, NumberPropertyConfig).

When you receive a JSON object representing Notion database properties, unmarshaling it into PropertyConfigs will allow you to access type-specific fields after performing a type assertion.

// Example of how PropertyConfigs handles polymorphic JSON
var configs PropertyConfigs
err := json.Unmarshal(jsonData, &configs)
if err != nil {
    // handle error
}

// Accessing a specific property type via type assertion
for name, config := range configs {
    switch c := config.(type) {
    case *notionapi.NumberPropertyConfig:
        fmt.Printf("Property %s is a number with format: %v\n", name, c.Number.Format)
    case *notionapi.TitlePropertyConfig:
        fmt.Printf("Property %s is a title\n", name)
    }
}