feat: reimplement Notion sync on REST data sources (fix-merge PR #2759)

Adds internal/notion/ package with direct REST API client, field mapping,
and tracker adapter. Adds bd notion init/connect/status/sync commands.
Enhances tracker engine: conflict detection before pull, label sync,
no-op skip, batch push interface, RFC3339Nano timestamps. Removed dead
matchesFetchOptions function, added gosec nolint for Notion API client.

Co-Authored-By: Osamu Okano <okano.osamu@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
emma 2026-03-27 19:20:24 -07:00 • committed by Steve Yegge
commit 083181e1ea
18 changed files with 5482 additions and 61 deletions

670
cmd/bd/notion.go Normal file
View file

@ -0,0 +1,670 @@
package main
import (
"context"
"encoding/json"
"fmt"
"os"
"sort"
"strings"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/notion"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/tracker"
"github.com/steveyegge/beads/internal/types"
)
type notionConfig struct {
DataSourceID string
ViewURL string
}
type notionUnsupportedPushStats struct {
counts map[types.IssueType]int
}
func newNotionUnsupportedPushStats() *notionUnsupportedPushStats {
return &notionUnsupportedPushStats{counts: make(map[types.IssueType]int)}
}
func (s *notionUnsupportedPushStats) record(issueType types.IssueType) {
if s == nil || strings.TrimSpace(string(issueType)) == "" {
return
}
s.counts[issueType]++
}
func (s *notionUnsupportedPushStats) warningText() string {
if s == nil || len(s.counts) == 0 {
return ""
}
parts := make([]string, 0, len(s.counts))
for issueType, count := range s.counts {
parts = append(parts, fmt.Sprintf("%s=%d", issueType, count))
}
sort.Strings(parts)
return fmt.Sprintf(
"Skipped unsupported Notion issue types: %s (supported: bug, feature, task, epic, chore)",
strings.Join(parts, ", "),
)
}
type notionSetupResult struct {
Action string `json:"action"`
DatabaseID string `json:"database_id,omitempty"`
DataSourceID string `json:"data_source_id,omitempty"`
ViewURL string `json:"view_url,omitempty"`
Message string `json:"message,omitempty"`
}
var (
notionInitParent string
notionInitTitle string
notionConnectURL string
notionSyncPull bool
notionSyncPush bool
notionSyncDryRun bool
notionPreferLocal bool
notionPreferNotion bool
notionCreateOnly bool
notionSyncState string
)
var newNotionStatusClient = notion.NewClient
var newNotionSetupClient = notion.NewClient
var notionCmd = &cobra.Command{
Use: "notion",
Short: "Notion integration commands",
Long: "Commands for syncing issues between beads and Notion.",
}
var notionStatusCmd = &cobra.Command{
Use: "status",
Short: "Show Notion sync status",
RunE: runNotionStatus,
}
var notionInitCmd = &cobra.Command{
Use: "init",
Short: "Create a dedicated Beads database in Notion",
RunE: runNotionInit,
}
var notionConnectCmd = &cobra.Command{
Use: "connect",
Short: "Connect bd to an existing Notion database or data source",
RunE: runNotionConnect,
}
var notionSyncCmd = &cobra.Command{
Use: "sync",
Short: "Sync issues with Notion",
Long: "Synchronize issues between beads and Notion.\n\n" +
"By default this performs bidirectional sync. Use --pull or --push to limit direction.",
RunE: runNotionSync,
}
func init() {
notionInitCmd.Flags().StringVar(&notionInitParent, "parent", "", "Parent page ID")
notionInitCmd.Flags().StringVar(&notionInitTitle, "title", notion.DefaultDatabaseTitle, "Database title")
_ = notionInitCmd.MarkFlagRequired("parent")
notionConnectCmd.Flags().StringVar(&notionConnectURL, "url", "", "Existing Notion database or data source URL")
_ = notionConnectCmd.MarkFlagRequired("url")
notionSyncCmd.Flags().BoolVar(&notionSyncPull, "pull", false, "Only pull issues from Notion")
notionSyncCmd.Flags().BoolVar(&notionSyncPush, "push", false, "Only push issues to Notion")
notionSyncCmd.Flags().BoolVar(&notionSyncDryRun, "dry-run", false, "Preview changes without making mutations")
notionSyncCmd.Flags().BoolVar(&notionPreferLocal, "prefer-local", false, "On conflict, keep the local beads version")
notionSyncCmd.Flags().BoolVar(&notionPreferNotion, "prefer-notion", false, "On conflict, use the Notion version")
notionSyncCmd.Flags().BoolVar(&notionCreateOnly, "create-only", false, "Only create missing remote pages, do not update existing ones")
notionSyncCmd.Flags().StringVar(&notionSyncState, "state", "all", "Issue state to sync: open, closed, or all")
notionCmd.AddCommand(
notionInitCmd,
notionConnectCmd,
notionStatusCmd,
notionSyncCmd,
)
rootCmd.AddCommand(notionCmd)
}
func getNotionConfig() notionConfig {
ctx := context.Background()
return notionConfig{
DataSourceID: getNotionConfigValue(ctx, "notion.data_source_id", "NOTION_DATA_SOURCE_ID"),
ViewURL: getNotionConfigValue(ctx, "notion.view_url", "NOTION_VIEW_URL"),
}
}
func getNotionConfigValue(ctx context.Context, key, envVar string) string {
if store != nil {
value, _ := store.GetConfig(ctx, key)
if strings.TrimSpace(value) != "" {
return strings.TrimSpace(value)
}
} else if dbPath != "" {
tempStore, err := openReadOnlyStoreForDBPath(ctx, dbPath)
if err == nil {
defer func() { _ = tempStore.Close() }()
value, _ := tempStore.GetConfig(ctx, key)
if strings.TrimSpace(value) != "" {
return strings.TrimSpace(value)
}
}
}
if envVar != "" {
return strings.TrimSpace(os.Getenv(envVar))
}
return ""
}
func resolveNotionAuth(ctx context.Context) (*notion.ResolvedAuth, error) {
if store != nil {
return notion.ResolveAuth(ctx, store)
}
if dbPath != "" {
tempStore, err := openReadOnlyStoreForDBPath(ctx, dbPath)
if err == nil {
defer func() { _ = tempStore.Close() }()
return notion.ResolveAuth(ctx, tempStore)
}
}
if token := strings.TrimSpace(os.Getenv("NOTION_TOKEN")); token != "" {
return &notion.ResolvedAuth{Token: token, Source: notion.AuthSourceEnv}, nil
}
return nil, nil
}
func validateNotionConfig(cfg notionConfig, auth *notion.ResolvedAuth) error {
if auth == nil || strings.TrimSpace(auth.Token) == "" {
return fmt.Errorf("Notion authentication is not configured. Set notion.token with 'bd config set notion.token <token>', or export NOTION_TOKEN")
}
if cfg.DataSourceID == "" {
return fmt.Errorf("notion.data_source_id is not configured. Run 'bd notion init --parent <page-id>' or 'bd notion connect --url <notion-url>', or set it directly via bd config set notion.data_source_id <id> or NOTION_DATA_SOURCE_ID")
}
return nil
}
func validateNotionToken(auth *notion.ResolvedAuth) error {
if auth == nil || strings.TrimSpace(auth.Token) == "" {
return fmt.Errorf("Notion authentication is not configured. Set notion.token with 'bd config set notion.token <token>', or export NOTION_TOKEN")
}
return nil
}
func maskNotionAuth(auth *notion.ResolvedAuth) string {
if auth == nil || strings.TrimSpace(auth.Token) == "" {
return "(not set)"
}
token := auth.Token
if len(token) <= 4 {
return "****"
}
return token[:4] + "****"
}
func runNotionStatus(cmd *cobra.Command, _ []string) error {
cfg := getNotionConfig()
auth, err := resolveNotionAuth(cmd.Context())
if err != nil {
return err
}
result := notion.StatusResponse{
Configured: auth != nil && strings.TrimSpace(auth.Token) != "" && cfg.DataSourceID != "",
DataSourceID: cfg.DataSourceID,
ViewURL: cfg.ViewURL,
}
if auth != nil && strings.TrimSpace(auth.Token) != "" {
result.Auth = &notion.StatusAuth{OK: true, Source: string(auth.Source)}
} else {
result.Auth = &notion.StatusAuth{OK: false}
}
if !result.Configured {
if err := validateNotionConfig(cfg, auth); err != nil {
result.Error = err.Error()
}
if jsonOutput {
return writeNotionJSON(cmd, result)
}
return renderNotionStatus(cmd, auth, cfg, &result)
}
client := newNotionStatusClient(auth.Token)
ctx := cmd.Context()
user, err := client.GetCurrentUser(ctx)
if err != nil {
result.Error = err.Error()
result.Auth = &notion.StatusAuth{OK: false, Source: string(auth.Source)}
} else {
result.Auth = &notion.StatusAuth{
OK: true,
Source: string(auth.Source),
User: statusUserFromNotionUser(user),
}
}
dataSource, dsErr := client.RetrieveDataSource(ctx, cfg.DataSourceID)
if dsErr != nil {
if result.Error == "" {
result.Error = dsErr.Error()
}
} else {
result.Database = &notion.StatusDatabase{
ID: dataSource.ID,
Title: notion.DataSourceTitle(dataSource.Title),
URL: dataSource.URL,
}
result.Schema = notion.ValidateDataSourceSchema(dataSource)
result.Ready = result.Auth != nil && result.Auth.OK && len(result.Schema.Missing) == 0
}
if jsonOutput {
return writeNotionJSON(cmd, result)
}
return renderNotionStatus(cmd, auth, cfg, &result)
}
func runNotionInit(cmd *cobra.Command, _ []string) error {
CheckReadonly("notion init")
if err := ensureStoreActive(); err != nil {
return fmt.Errorf("database not available: %w", err)
}
auth, err := resolveNotionAuth(cmd.Context())
if err != nil {
return err
}
if err := validateNotionToken(auth); err != nil {
return err
}
client := newNotionSetupClient(auth.Token)
db, err := client.CreateDatabase(cmd.Context(), notionInitParent, notionInitTitle)
if err != nil {
return err
}
if len(db.DataSources) == 0 || strings.TrimSpace(db.DataSources[0].ID) == "" {
return fmt.Errorf("Notion create database response did not include a child data source")
}
result := notionSetupResult{
Action: "init",
DatabaseID: strings.TrimSpace(db.ID),
DataSourceID: strings.TrimSpace(db.DataSources[0].ID),
ViewURL: strings.TrimSpace(db.URL),
Message: "Notion target initialized",
}
if err := saveNotionTargetConfig(cmd.Context(), result.DataSourceID, result.ViewURL); err != nil {
return err
}
if jsonOutput {
return writeNotionJSON(cmd, result)
}
_, _ = fmt.Fprintf(cmd.OutOrStdout(), "✓ Created Notion database %s\n", firstNonEmpty(result.DatabaseID, "(unknown)"))
_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Saved data source: %s\n", result.DataSourceID)
if result.ViewURL != "" {
_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Launch URL: %s\n", result.ViewURL)
}
return nil
}
func runNotionConnect(cmd *cobra.Command, _ []string) error {
CheckReadonly("notion connect")
if err := ensureStoreActive(); err != nil {
return fmt.Errorf("database not available: %w", err)
}
auth, err := resolveNotionAuth(cmd.Context())
if err != nil {
return err
}
if err := validateNotionToken(auth); err != nil {
return err
}
client := newNotionSetupClient(auth.Token)
resolved, err := notion.ResolveDataSourceReference(cmd.Context(), client, notionConnectURL)
if err != nil {
return err
}
schema := notion.ValidateDataSourceSchema(resolved.DataSource)
if len(schema.Missing) > 0 {
return fmt.Errorf("target is missing required Notion properties: %s", strings.Join(schema.Missing, ", "))
}
result := notionSetupResult{
Action: "connect",
DatabaseID: "",
DataSourceID: resolved.DataSourceID,
ViewURL: strings.TrimSpace(notionConnectURL),
Message: "Notion target connected",
}
if resolved.Database != nil {
result.DatabaseID = strings.TrimSpace(resolved.Database.ID)
}
if err := saveNotionTargetConfig(cmd.Context(), result.DataSourceID, result.ViewURL); err != nil {
return err
}
if jsonOutput {
return writeNotionJSON(cmd, result)
}
_, _ = fmt.Fprintf(cmd.OutOrStdout(), "✓ Connected Notion data source %s\n", result.DataSourceID)
if result.ViewURL != "" {
_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Launch URL: %s\n", result.ViewURL)
}
return nil
}
func renderNotionStatus(cmd *cobra.Command, auth *notion.ResolvedAuth, cfg notionConfig, result *notion.StatusResponse) error {
out := cmd.OutOrStdout()
_, _ = fmt.Fprintln(out, "Notion Configuration")
_, _ = fmt.Fprintln(out, "====================")
_, _ = fmt.Fprintf(out, "Auth: %s\n", maskNotionAuth(auth))
if auth != nil && auth.Source != "" {
_, _ = fmt.Fprintf(out, "Auth source: %s\n", auth.Source)
}
_, _ = fmt.Fprintf(out, "Data source: %s\n", cfg.DataSourceID)
if cfg.ViewURL != "" {
_, _ = fmt.Fprintf(out, "View URL: %s\n", cfg.ViewURL)
}
if result.Database != nil {
_, _ = fmt.Fprintf(out, "Database: %s\n", result.Database.Title)
}
statusLine := "○ Not configured"
switch {
case result.Ready:
statusLine = "✓ Ready"
case result.Configured:
statusLine = "◐ Not ready"
}
_, _ = fmt.Fprintf(out, "\nStatus: %s\n", statusLine)
if result.Error != "" {
_, _ = fmt.Fprintf(out, "Error: %s\n", result.Error)
}
if result.Schema != nil {
if len(result.Schema.Missing) == 0 {
_, _ = fmt.Fprintln(out, "Schema: ✓ Required properties present")
} else {
_, _ = fmt.Fprintf(out, "Schema: missing %s\n", strings.Join(result.Schema.Missing, ", "))
}
}
return nil
}
func runNotionSync(cmd *cobra.Command, _ []string) error {
cfg := getNotionConfig()
auth, err := resolveNotionAuth(cmd.Context())
if err != nil {
return err
}
if err := validateNotionConfig(cfg, auth); err != nil {
return err
}
if !notionSyncDryRun {
CheckReadonly("notion sync")
}
if notionPreferLocal && notionPreferNotion {
return fmt.Errorf("cannot use both --prefer-local and --prefer-notion")
}
if notionSyncPull && notionSyncPush {
return fmt.Errorf("cannot use both --pull and --push")
}
if err := ensureStoreActive(); err != nil {
return fmt.Errorf("database not available: %w", err)
}
ctx := cmd.Context()
nt := &notion.Tracker{}
if err := nt.Init(ctx, store); err != nil {
return fmt.Errorf("initializing Notion tracker: %w", err)
}
engine := tracker.NewEngine(nt, store, actor)
engine.PullHooks = buildNotionPullHooks(ctx)
unsupportedStats := newNotionUnsupportedPushStats()
engine.PushHooks = buildNotionPushHooks(ctx, nt, unsupportedStats)
if jsonOutput {
engine.OnMessage = func(msg string) { _, _ = fmt.Fprintln(cmd.ErrOrStderr(), " "+msg) }
} else {
engine.OnMessage = func(msg string) { _, _ = fmt.Fprintln(cmd.OutOrStdout(), " "+msg) }
}
engine.OnWarning = func(msg string) { _, _ = fmt.Fprintf(cmd.ErrOrStderr(), "Warning: %s\n", msg) }
pull := true
push := true
if notionSyncPull {
push = false
}
if notionSyncPush {
pull = false
}
conflictResolution := tracker.ConflictTimestamp
if notionPreferLocal {
conflictResolution = tracker.ConflictLocal
}
if notionPreferNotion {
conflictResolution = tracker.ConflictExternal
}
result, err := engine.Sync(ctx, tracker.SyncOptions{
Pull: pull,
Push: push,
DryRun: notionSyncDryRun,
CreateOnly: notionCreateOnly,
State: notionSyncState,
ExcludeEphemeral: true,
ConflictResolution: conflictResolution,
})
if err != nil {
return err
}
if warning := unsupportedStats.warningText(); warning != "" {
result.Warnings = append(result.Warnings, warning)
}
if jsonOutput {
return writeNotionJSON(cmd, result)
}
return renderNotionSyncResult(cmd, result)
}
func renderNotionSyncResult(cmd *cobra.Command, result *tracker.SyncResult) error {
out := cmd.OutOrStdout()
if notionSyncDryRun {
_, _ = fmt.Fprintln(out, "Dry run mode")
}
if result.PullStats.Queried > 0 || result.PullStats.Candidates > 0 {
_, _ = fmt.Fprintf(out, "Queried %d pages from Notion (%d pull candidates)\n",
result.PullStats.Queried, result.PullStats.Candidates)
}
if result.PullStats.Created > 0 || result.PullStats.Updated > 0 {
_, _ = fmt.Fprintf(out, "✓ Pulled %d issues (%d created, %d updated)\n",
result.Stats.Pulled, result.PullStats.Created, result.PullStats.Updated)
}
if result.PushStats.Created > 0 || result.PushStats.Updated > 0 {
_, _ = fmt.Fprintf(out, "✓ Pushed %d issues (%d created, %d updated)\n",
result.Stats.Pushed, result.PushStats.Created, result.PushStats.Updated)
}
if result.Stats.Conflicts > 0 {
_, _ = fmt.Fprintf(out, "◐ Resolved %d conflicts\n", result.Stats.Conflicts)
}
for _, line := range summarizeNotionSyncWarnings(result.Warnings) {
_, _ = fmt.Fprintln(out, line)
}
if notionSyncDryRun {
_, _ = fmt.Fprintln(out, "Run without --dry-run to apply changes")
}
return nil
}
func summarizeNotionSyncWarnings(warnings []string) []string {
staleTargetCount := 0
for _, warning := range warnings {
warning = strings.TrimSpace(warning)
switch {
case warning == "":
continue
case strings.HasPrefix(warning, "Skipped unsupported Notion issue types:"):
continue
case strings.Contains(warning, "outside the current target"):
staleTargetCount++
}
}
if staleTargetCount == 0 {
return nil
}
return []string{
fmt.Sprintf("Skipped %d linked issues that still point at a different Notion target. Clear external_ref to recreate them in this data source.", staleTargetCount),
}
}
func buildNotionPullHooks(ctx context.Context) *tracker.PullHooks {
prefix := "bd"
if p := config.GetString("issue-prefix"); p != "" {
prefix = p
} else if store != nil {
if p, err := store.GetConfig(ctx, "issue_prefix"); err == nil && p != "" {
prefix = p
}
}
return &tracker.PullHooks{
GenerateID: func(_ context.Context, issue *types.Issue) error {
if issue.ID == "" {
issue.ID = generateIssueID(prefix)
}
return nil
},
}
}
func buildNotionPushHooks(ctx context.Context, tr tracker.IssueTracker, stats *notionUnsupportedPushStats) *tracker.PushHooks {
return &tracker.PushHooks{
ShouldPush: func(issue *types.Issue) bool {
if issue == nil || tr == nil {
return false
}
if notion.SupportsIssueType(issue.IssueType, nil) {
pushPrefix, _ := store.GetConfig(ctx, "notion.push_prefix")
pushLabel, _ := store.GetConfig(ctx, "notion.push_label")
return shouldPushNotionIssue(issue, tr, pushPrefix, pushLabel)
}
stats.record(issue.IssueType)
return false
},
}
}
func shouldPushNotionIssue(issue *types.Issue, tr tracker.IssueTracker, pushPrefix, pushLabel string) bool {
if issue == nil || tr == nil {
return false
}
if issue.ExternalRef != nil && strings.TrimSpace(*issue.ExternalRef) != "" {
return tr.IsExternalRef(*issue.ExternalRef)
}
if strings.TrimSpace(pushLabel) != "" && !matchesNotionPushLabel(issue, pushLabel) {
return false
}
if strings.TrimSpace(pushPrefix) == "" {
return true
}
for _, prefix := range strings.Split(pushPrefix, ",") {
prefix = strings.TrimSpace(prefix)
prefix = strings.TrimSuffix(prefix, "-")
if prefix != "" && strings.HasPrefix(issue.ID, prefix+"-") {
return true
}
}
return false
}
func matchesNotionPushLabel(issue *types.Issue, pushLabel string) bool {
if issue == nil || strings.TrimSpace(pushLabel) == "" {
return false
}
configured := make(map[string]struct{})
for _, raw := range strings.Split(pushLabel, ",") {
label := strings.ToLower(strings.TrimSpace(raw))
if label != "" {
configured[label] = struct{}{}
}
}
if len(configured) == 0 {
return false
}
for _, raw := range issue.Labels {
label := strings.ToLower(strings.TrimSpace(raw))
if _, ok := configured[label]; ok {
return true
}
}
return false
}
func saveNotionTargetConfig(ctx context.Context, dataSourceID, viewURL string) error {
if store == nil {
return fmt.Errorf("database not available")
}
if err := store.SetConfig(ctx, "notion.data_source_id", strings.TrimSpace(dataSourceID)); err != nil {
return fmt.Errorf("save notion.data_source_id: %w", err)
}
viewURL = strings.TrimSpace(viewURL)
if viewURL == "" {
deleter, ok := store.(storage.ConfigMetadataStore)
if !ok {
return fmt.Errorf("store does not support config deletion")
}
if err := deleter.DeleteConfig(ctx, "notion.view_url"); err != nil {
return fmt.Errorf("clear notion.view_url: %w", err)
}
return nil
}
if err := store.SetConfig(ctx, "notion.view_url", viewURL); err != nil {
return fmt.Errorf("save notion.view_url: %w", err)
}
return nil
}
func writeNotionJSON(cmd *cobra.Command, value interface{}) error {
encoder := json.NewEncoder(cmd.OutOrStdout())
encoder.SetIndent("", " ")
return encoder.Encode(value)
}
func firstNonEmpty(values ...string) string {
for _, value := range values {
if strings.TrimSpace(value) != "" {
return strings.TrimSpace(value)
}
}
return ""
}
func statusUserFromNotionUser(user *notion.User) *notion.StatusUser {
if user == nil {
return nil
}
return &notion.StatusUser{
ID: user.ID,
Name: user.Name,
Type: user.Type,
Email: userEmail(user),
}
}
func userEmail(user *notion.User) string {
if user == nil || user.Person == nil {
return ""
}
return user.Person.Email
}

516
cmd/bd/notion_test.go Normal file
View file

@ -0,0 +1,516 @@
//go:build cgo
package main
import (
"bytes"
"context"
"encoding/json"
"io"
"net/http"
"net/http/httptest"
"path/filepath"
"strings"
"testing"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/notion"
"github.com/steveyegge/beads/internal/tracker"
"github.com/steveyegge/beads/internal/types"
)
func TestNotionCommandsRegistered(t *testing.T) {
t.Parallel()
for _, name := range []string{"init", "connect", "status", "sync"} {
if _, _, err := notionCmd.Find([]string{name}); err != nil {
t.Fatalf("missing subcommand %q: %v", name, err)
}
}
}
func TestGetNotionConfigPrefersStoreOverEnv(t *testing.T) {
saveAndRestoreGlobals(t)
ctx := context.Background()
testStore, cleanup := setupTestDB(t)
defer cleanup()
store = testStore
if err := store.SetConfig(ctx, "notion.token", "store-token"); err != nil {
t.Fatalf("SetConfig(notion.token): %v", err)
}
if err := store.SetConfig(ctx, "notion.data_source_id", "store-ds"); err != nil {
t.Fatalf("SetConfig(notion.data_source_id): %v", err)
}
if err := store.SetConfig(ctx, "notion.view_url", "https://store/view"); err != nil {
t.Fatalf("SetConfig(notion.view_url): %v", err)
}
t.Setenv("NOTION_TOKEN", "env-token")
t.Setenv("NOTION_DATA_SOURCE_ID", "env-ds")
t.Setenv("NOTION_VIEW_URL", "https://env/view")
cfg := getNotionConfig()
if cfg.DataSourceID != "store-ds" || cfg.ViewURL != "https://store/view" {
t.Fatalf("config = %+v", cfg)
}
}
func TestRunNotionStatusJSONWithMissingConfig(t *testing.T) {
saveAndRestoreGlobals(t)
jsonOutput = true
store = nil
dbPath = ""
t.Setenv("NOTION_TOKEN", "")
t.Setenv("NOTION_DATA_SOURCE_ID", "")
t.Setenv("NOTION_VIEW_URL", "")
cmd := &cobra.Command{}
var stdout bytes.Buffer
cmd.SetOut(&stdout)
cmd.SetContext(context.Background())
if err := runNotionStatus(cmd, nil); err != nil {
t.Fatalf("runNotionStatus returned error: %v", err)
}
var resp notion.StatusResponse
if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
t.Fatalf("unmarshal status json: %v\n%s", err, stdout.String())
}
if resp.Configured {
t.Fatal("expected configured=false")
}
if !strings.Contains(resp.Error, "bd config set notion.token") {
t.Fatalf("error = %q", resp.Error)
}
}
func TestRunNotionInitPersistsTargetConfig(t *testing.T) {
saveAndRestoreGlobals(t)
ctx := context.Background()
testStore, cleanup := setupTestDB(t)
defer cleanup()
store = testStore
jsonOutput = true
notionInitParent = "329e5bf9-7fae-8080-bb4a-d94e1387655d"
notionInitTitle = "Beads Issues"
t.Setenv("NOTION_TOKEN", "env-token")
originalFactory := newNotionSetupClient
t.Cleanup(func() { newNotionSetupClient = originalFactory })
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/databases" {
t.Fatalf("unexpected path %q", r.URL.Path)
}
body, _ := io.ReadAll(r.Body)
for _, want := range []string{
`"page_id":"329e5bf9-7fae-8080-bb4a-d94e1387655d"`,
`"initial_data_source"`,
`"Beads ID"`,
`"Status"`,
} {
if !strings.Contains(string(body), want) {
t.Fatalf("request body missing %q\n%s", want, body)
}
}
_, _ = io.WriteString(w, `{"id":"db_123","url":"https://www.notion.so/db123","data_sources":[{"id":"ds_123","name":"Beads Issues"}]}`)
}))
defer server.Close()
newNotionSetupClient = func(token string) *notion.Client {
return notion.NewClient(token).WithBaseURL(server.URL)
}
cmd := &cobra.Command{}
var stdout bytes.Buffer
cmd.SetOut(&stdout)
cmd.SetContext(ctx)
if err := runNotionInit(cmd, nil); err != nil {
t.Fatalf("runNotionInit returned error: %v", err)
}
dataSourceID, err := store.GetConfig(ctx, "notion.data_source_id")
if err != nil || dataSourceID != "ds_123" {
t.Fatalf("notion.data_source_id = %q, err=%v", dataSourceID, err)
}
viewURL, err := store.GetConfig(ctx, "notion.view_url")
if err != nil || viewURL != "https://www.notion.so/db123" {
t.Fatalf("notion.view_url = %q, err=%v", viewURL, err)
}
}
func TestRunNotionConnectResolvesDataSourceURL(t *testing.T) {
saveAndRestoreGlobals(t)
ctx := context.Background()
testStore, cleanup := setupTestDB(t)
defer cleanup()
store = testStore
t.Setenv("NOTION_TOKEN", "env-token")
notionConnectURL = "https://www.notion.so/workspace/329e5bf97fae8080bb4ad94e1387655d"
originalFactory := newNotionSetupClient
t.Cleanup(func() { newNotionSetupClient = originalFactory })
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case "/data_sources/329e5bf9-7fae-8080-bb4a-d94e1387655d":
_, _ = io.WriteString(w, `{"id":"329e5bf9-7fae-8080-bb4a-d94e1387655d","properties":{"Name":{"type":"title"},"Beads ID":{"type":"rich_text"},"Status":{"type":"select"},"Priority":{"type":"select"},"Type":{"type":"select"},"Description":{"type":"rich_text"},"Assignee":{"type":"rich_text"},"Labels":{"type":"multi_select"}}}`)
default:
t.Fatalf("unexpected path %q", r.URL.Path)
}
}))
defer server.Close()
newNotionSetupClient = func(token string) *notion.Client {
return notion.NewClient(token).WithBaseURL(server.URL)
}
cmd := &cobra.Command{}
cmd.SetContext(ctx)
if err := runNotionConnect(cmd, nil); err != nil {
t.Fatalf("runNotionConnect returned error: %v", err)
}
dataSourceID, err := store.GetConfig(ctx, "notion.data_source_id")
if err != nil || dataSourceID != "329e5bf9-7fae-8080-bb4a-d94e1387655d" {
t.Fatalf("notion.data_source_id = %q, err=%v", dataSourceID, err)
}
}
func TestRunNotionConnectResolvesDatabaseURL(t *testing.T) {
saveAndRestoreGlobals(t)
ctx := context.Background()
testStore, cleanup := setupTestDB(t)
defer cleanup()
store = testStore
t.Setenv("NOTION_TOKEN", "env-token")
notionConnectURL = "https://www.notion.so/workspace/429e5bf97fae8080bb4ad94e1387655d"
originalFactory := newNotionSetupClient
t.Cleanup(func() { newNotionSetupClient = originalFactory })
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case "/data_sources/429e5bf9-7fae-8080-bb4a-d94e1387655d":
w.WriteHeader(http.StatusNotFound)
_, _ = io.WriteString(w, `{"code":"object_not_found","message":"not found"}`)
case "/databases/429e5bf9-7fae-8080-bb4a-d94e1387655d":
_, _ = io.WriteString(w, `{"id":"429e5bf9-7fae-8080-bb4a-d94e1387655d","data_sources":[{"id":"529e5bf9-7fae-8080-bb4a-d94e1387655d","name":"Beads Issues"}]}`)
case "/data_sources/529e5bf9-7fae-8080-bb4a-d94e1387655d":
_, _ = io.WriteString(w, `{"id":"529e5bf9-7fae-8080-bb4a-d94e1387655d","properties":{"Name":{"type":"title"},"Beads ID":{"type":"rich_text"},"Status":{"type":"select"},"Priority":{"type":"select"},"Type":{"type":"select"},"Description":{"type":"rich_text"},"Assignee":{"type":"rich_text"},"Labels":{"type":"multi_select"}}}`)
default:
t.Fatalf("unexpected path %q", r.URL.Path)
}
}))
defer server.Close()
newNotionSetupClient = func(token string) *notion.Client {
return notion.NewClient(token).WithBaseURL(server.URL)
}
cmd := &cobra.Command{}
cmd.SetContext(ctx)
if err := runNotionConnect(cmd, nil); err != nil {
t.Fatalf("runNotionConnect returned error: %v", err)
}
dataSourceID, err := store.GetConfig(ctx, "notion.data_source_id")
if err != nil || dataSourceID != "529e5bf9-7fae-8080-bb4a-d94e1387655d" {
t.Fatalf("notion.data_source_id = %q, err=%v", dataSourceID, err)
}
}
func TestRunNotionStatusUsesHTTPClient(t *testing.T) {
saveAndRestoreGlobals(t)
originalFactory := newNotionStatusClient
t.Cleanup(func() { newNotionStatusClient = originalFactory })
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case "/users/me":
if got := r.Header.Get("Authorization"); got != "Bearer env-token" {
t.Fatalf("authorization = %q", got)
}
_, _ = io.WriteString(w, `{"id":"user-1","name":"Osamu","type":"person","person":{"email":"osamu@example.com"}}`)
case "/data_sources/ds_123":
_, _ = io.WriteString(w, `{"id":"ds_123","url":"https://www.notion.so/source","title":[{"plain_text":"Tasks"}],"properties":{"Name":{"type":"title"},"Beads ID":{"type":"rich_text"},"Status":{"type":"select"},"Priority":{"type":"select"},"Type":{"type":"select"},"Description":{"type":"rich_text"},"Assignee":{"type":"rich_text"},"Labels":{"type":"multi_select"}}}`)
default:
t.Fatalf("unexpected path %q", r.URL.Path)
}
}))
defer server.Close()
newNotionStatusClient = func(token string) *notion.Client {
return notion.NewClient(token).WithBaseURL(server.URL)
}
jsonOutput = true
store = nil
dbPath = ""
t.Setenv("NOTION_TOKEN", "env-token")
t.Setenv("NOTION_DATA_SOURCE_ID", "ds_123")
t.Setenv("NOTION_VIEW_URL", "https://www.notion.so/view")
cmd := &cobra.Command{}
var stdout bytes.Buffer
cmd.SetOut(&stdout)
cmd.SetContext(context.Background())
if err := runNotionStatus(cmd, nil); err != nil {
t.Fatalf("runNotionStatus returned error: %v", err)
}
var resp notion.StatusResponse
if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
t.Fatalf("unmarshal status json: %v\n%s", err, stdout.String())
}
if !resp.Ready {
t.Fatalf("expected ready response, got %+v", resp)
}
if resp.Database == nil || resp.Database.Title != "Tasks" {
t.Fatalf("database = %+v", resp.Database)
}
if resp.Auth == nil || !resp.Auth.OK || resp.Auth.User == nil || resp.Auth.User.Email != "osamu@example.com" {
t.Fatalf("auth = %+v", resp.Auth)
}
if resp.Auth.Source != "env" {
t.Fatalf("auth source = %q", resp.Auth.Source)
}
}
func TestResolveNotionAuthPrefersConfigTokenOverEnv(t *testing.T) {
saveAndRestoreGlobals(t)
ctx := context.Background()
testStore, cleanup := setupTestDB(t)
defer cleanup()
store = testStore
if err := store.SetConfig(ctx, "notion.token", "config-token"); err != nil {
t.Fatalf("SetConfig(notion.token): %v", err)
}
t.Setenv("NOTION_TOKEN", "env-token")
auth, err := resolveNotionAuth(ctx)
if err != nil {
t.Fatalf("resolveNotionAuth returned error: %v", err)
}
if auth == nil || auth.Token != "config-token" || auth.Source != notion.AuthSourceConfigToken {
t.Fatalf("auth = %+v", auth)
}
}
func TestRenderNotionSyncResultUsesPhaseStats(t *testing.T) {
saveAndRestoreGlobals(t)
notionSyncDryRun = true
t.Cleanup(func() { notionSyncDryRun = false })
cmd := &cobra.Command{}
var stdout bytes.Buffer
cmd.SetOut(&stdout)
err := renderNotionSyncResult(cmd, &tracker.SyncResult{
Stats: tracker.SyncStats{Pulled: 2, Pushed: 3, Conflicts: 1},
Warnings: []string{
"Skipped unsupported Notion issue types: event=2",
"Skipped bd-1: Notion external_ref points outside the current target; clear external_ref to recreate it in this data source",
"Skipped bd-2: Notion external_ref points outside the current target; clear external_ref to recreate it in this data source",
},
PullStats: tracker.PullStats{
Queried: 12,
Candidates: 2,
Created: 1,
Updated: 1,
},
PushStats: tracker.PushStats{
Created: 2,
Updated: 1,
},
})
if err != nil {
t.Fatalf("renderNotionSyncResult returned error: %v", err)
}
out := stdout.String()
for _, want := range []string{
"Dry run mode",
"Queried 12 pages from Notion (2 pull candidates)",
"Pulled 2 issues (1 created, 1 updated)",
"Pushed 3 issues (2 created, 1 updated)",
"Resolved 1 conflicts",
"Skipped 2 linked issues that still point at a different Notion target. Clear external_ref to recreate them in this data source.",
} {
if !strings.Contains(out, want) {
t.Fatalf("stdout missing %q\n%s", want, out)
}
}
for _, unwanted := range []string{
"event=2",
"bd-1",
"bd-2",
} {
if strings.Contains(out, unwanted) {
t.Fatalf("stdout unexpectedly contained %q\n%s", unwanted, out)
}
}
}
func TestRenderNotionSyncResultOmitsMutationSummaryForSameMinuteNoopDryRun(t *testing.T) {
saveAndRestoreGlobals(t)
notionSyncDryRun = true
t.Cleanup(func() { notionSyncDryRun = false })
cmd := &cobra.Command{}
var stdout bytes.Buffer
cmd.SetOut(&stdout)
err := renderNotionSyncResult(cmd, &tracker.SyncResult{
PullStats: tracker.PullStats{
Queried: 49,
Candidates: 3,
},
})
if err != nil {
t.Fatalf("renderNotionSyncResult returned error: %v", err)
}
out := stdout.String()
for _, want := range []string{
"Dry run mode",
"Queried 49 pages from Notion (3 pull candidates)",
"Run without --dry-run to apply changes",
} {
if !strings.Contains(out, want) {
t.Fatalf("stdout missing %q\n%s", want, out)
}
}
for _, unwanted := range []string{
"Pulled ",
"Pushed ",
"Resolved ",
} {
if strings.Contains(out, unwanted) {
t.Fatalf("stdout unexpectedly contained %q\n%s", unwanted, out)
}
}
}
func TestValidateNotionConfigMessages(t *testing.T) {
t.Parallel()
err := validateNotionConfig(notionConfig{}, nil)
if err == nil || !strings.Contains(err.Error(), "bd config set notion.token") {
t.Fatalf("err = %v", err)
}
err = validateNotionConfig(notionConfig{}, &notion.ResolvedAuth{Token: "token", Source: notion.AuthSourceConfigToken})
if err == nil || !strings.Contains(err.Error(), "bd notion init") {
t.Fatalf("err = %v", err)
}
}
func TestGetNotionConfigReadsDBPathWhenStoreUnset(t *testing.T) {
saveAndRestoreGlobals(t)
tempDir := t.TempDir()
testDBPath := filepath.Join(tempDir, "test.db")
testStore := newTestStore(t, testDBPath)
defer testStore.Close()
ctx := context.Background()
if err := testStore.SetConfig(ctx, "notion.token", "path-token"); err != nil {
t.Fatalf("SetConfig(notion.token): %v", err)
}
if err := testStore.SetConfig(ctx, "notion.data_source_id", "path-ds"); err != nil {
t.Fatalf("SetConfig(notion.data_source_id): %v", err)
}
store = nil
dbPath = testDBPath
t.Setenv("NOTION_TOKEN", "")
t.Setenv("NOTION_DATA_SOURCE_ID", "")
t.Setenv("NOTION_VIEW_URL", "")
cfg := getNotionConfig()
if cfg.DataSourceID != "path-ds" {
t.Fatalf("config = %+v", cfg)
}
}
func TestShouldPushNotionIssue(t *testing.T) {
t.Parallel()
tests := []struct {
name string
issue *types.Issue
pushPrefix string
pushLabel string
want bool
}{
{
name: "existing notion ref is allowed",
issue: func() *types.Issue {
extRef := "https://www.notion.so/Test-0123456789abcdef0123456789abcdef"
return &types.Issue{ID: "beads-1", ExternalRef: &extRef}
}(),
want: true,
},
{
name: "other tracker ref is rejected",
issue: func() *types.Issue {
extRef := "https://github.com/example/repo/issues/1"
return &types.Issue{ID: "beads-1", ExternalRef: &extRef}
}(),
want: false,
},
{
name: "unlinked issue is allowed when no gate is configured",
issue: &types.Issue{ID: "beads-1"},
want: true,
},
{
name: "prefix alone narrows issue set when no label gate is configured",
issue: &types.Issue{ID: "beads-1"},
pushPrefix: "beads",
want: true,
},
{
name: "prefix mismatch still rejects issue without label gate",
issue: &types.Issue{ID: "beads-1"},
pushPrefix: "proj",
want: false,
},
{
name: "configured label opts issue in",
issue: &types.Issue{ID: "beads-1", Labels: []string{"notion-sync"}},
pushLabel: "notion-sync",
want: true,
},
{
name: "configured label still gates unlinked issue",
issue: &types.Issue{ID: "beads-1"},
pushLabel: "notion-sync",
want: false,
},
{
name: "configured label is case insensitive",
issue: &types.Issue{ID: "beads-1", Labels: []string{"Notion-Sync"}},
pushLabel: "notion-sync",
want: true,
},
{
name: "label plus matching prefix allows issue",
issue: &types.Issue{ID: "beads-1", Labels: []string{"notion-sync"}},
pushPrefix: "beads",
pushLabel: "notion-sync",
want: true,
},
{
name: "label plus wrong prefix rejects issue",
issue: &types.Issue{ID: "beads-1", Labels: []string{"notion-sync"}},
pushPrefix: "proj",
pushLabel: "notion-sync",
want: false,
},
}
tr := &notion.Tracker{}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := shouldPushNotionIssue(tt.issue, tr, tt.pushPrefix, tt.pushLabel); got != tt.want {
t.Fatalf("shouldPushNotionIssue() = %v, want %v", got, tt.want)
}
})
}
}

View file

@ -197,6 +197,40 @@ When a teammate clones the repo, `bd bootstrap` auto-detects the existing databa
See [DOLT-BACKEND.md](DOLT-BACKEND.md#dolt-remotes) for remote configuration details and [FEDERATION-SETUP.md](../FEDERATION-SETUP.md) for multi-team sync.
## Optional: Notion Sync
If you keep project issues in Notion, save an integration token first:
```bash
bd config set notion.token <your-token>
```
Then either create a new Beads database under a parent page or connect to an existing target:
```bash
bd notion init --parent <page-id>
# or
bd notion connect --url <notion-database-or-data-source-url>
```
The same auth value can also come from `NOTION_TOKEN`. Directly setting `notion.data_source_id` remains available as an escape hatch for advanced setups.
Check which auth source is active and whether the target schema is ready:
```bash
bd notion status
bd notion status --json
```
Preview or run sync:
```bash
bd notion sync --dry-run
bd notion sync
bd notion sync --pull
bd notion sync --push
```
## Database Location
By default, data is stored in `.beads/dolt/` within your repository.

39
internal/notion/auth.go Normal file
View file

@ -0,0 +1,39 @@
package notion
import (
"context"
"os"
"strings"
"github.com/steveyegge/beads/internal/storage"
)
const configKeyToken = "notion.token"
type AuthSource string
const (
AuthSourceConfigToken AuthSource = "config_token"
AuthSourceEnv AuthSource = "env"
)
type ResolvedAuth struct {
Token string
Source AuthSource
}
func ResolveAuth(ctx context.Context, store storage.Storage) (*ResolvedAuth, error) {
if store != nil {
if token, err := store.GetConfig(ctx, configKeyToken); err == nil && strings.TrimSpace(token) != "" {
return &ResolvedAuth{
Token: strings.TrimSpace(token),
Source: AuthSourceConfigToken,
}, nil
}
}
if token := strings.TrimSpace(os.Getenv("NOTION_TOKEN")); token != "" {
return &ResolvedAuth{Token: token, Source: AuthSourceEnv}, nil
}
return nil, nil
}

303
internal/notion/client.go Normal file
View file

@ -0,0 +1,303 @@
package notion
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"strings"
"time"
)
const (
DefaultBaseURL = "https://api.notion.com/v1"
DefaultNotionVersion = "2026-03-11"
DefaultTimeout = 30 * time.Second
maxResponseBytes = 20 * 1024 * 1024
maxQueryPages = 50
maxPageSize = 100
)
type Client struct {
Token string
BaseURL string
NotionVersion string
HTTPClient *http.Client
}
func NewClient(token string) *Client {
return &Client{
Token: token,
BaseURL: DefaultBaseURL,
NotionVersion: DefaultNotionVersion,
HTTPClient: &http.Client{Timeout: DefaultTimeout},
}
}
func (c *Client) WithHTTPClient(httpClient *http.Client) *Client {
clone := *c
clone.HTTPClient = httpClient
return &clone
}
func (c *Client) WithBaseURL(baseURL string) *Client {
clone := *c
clone.BaseURL = strings.TrimSuffix(baseURL, "/")
return &clone
}
func (c *Client) GetCurrentUser(ctx context.Context) (*User, error) {
body, err := c.doRequest(ctx, http.MethodGet, "/users/me", nil)
if err != nil {
return nil, err
}
var user User
if err := json.Unmarshal(body, &user); err != nil {
return nil, fmt.Errorf("parse current user response: %w", err)
}
return &user, nil
}
func (c *Client) RetrieveDataSource(ctx context.Context, dataSourceID string) (*DataSource, error) {
body, err := c.doRequest(ctx, http.MethodGet, "/data_sources/"+url.PathEscape(dataSourceID), nil)
if err != nil {
return nil, err
}
var ds DataSource
if err := json.Unmarshal(body, &ds); err != nil {
return nil, fmt.Errorf("parse data source response: %w", err)
}
return &ds, nil
}
func (c *Client) RetrieveDatabase(ctx context.Context, databaseID string) (*Database, error) {
body, err := c.doRequest(ctx, http.MethodGet, "/databases/"+url.PathEscape(databaseID), nil)
if err != nil {
return nil, err
}
var db Database
if err := json.Unmarshal(body, &db); err != nil {
return nil, fmt.Errorf("parse database response: %w", err)
}
return &db, nil
}
func (c *Client) CreateDatabase(ctx context.Context, parentPageID, title string) (*Database, error) {
parentPageID = strings.TrimSpace(parentPageID)
if parentPageID == "" {
return nil, fmt.Errorf("parent page ID is required")
}
title = strings.TrimSpace(title)
if title == "" {
title = DefaultDatabaseTitle
}
request := map[string]interface{}{
"parent": map[string]interface{}{
"type": "page_id",
"page_id": parentPageID,
},
"title": richTextRequest(title),
"is_inline": false,
"initial_data_source": map[string]interface{}{
"title": richTextRequest(title),
"properties": BuildInitialDataSourceProperties(),
},
}
body, err := c.doRequest(ctx, http.MethodPost, "/databases", request)
if err != nil {
return nil, err
}
var db Database
if err := json.Unmarshal(body, &db); err != nil {
return nil, fmt.Errorf("parse create database response: %w", err)
}
return &db, nil
}
func (c *Client) QueryDataSource(ctx context.Context, dataSourceID string) ([]Page, error) {
var pages []Page
var cursor string
for pageNum := 0; pageNum < maxQueryPages; pageNum++ {
request := map[string]interface{}{
"page_size": maxPageSize,
"result_type": "page",
"in_trash": false,
}
if cursor != "" {
request["start_cursor"] = cursor
}
body, err := c.doRequest(ctx, http.MethodPost, "/data_sources/"+url.PathEscape(dataSourceID)+"/query", request)
if err != nil {
return nil, err
}
var resp QueryDataSourceResponse
if err := json.Unmarshal(body, &resp); err != nil {
return nil, fmt.Errorf("parse data source query response: %w", err)
}
pages = append(pages, resp.Results...)
if !resp.HasMore || resp.NextCursor == "" {
return pages, nil
}
cursor = resp.NextCursor
}
return nil, fmt.Errorf("query pagination exceeded %d pages", maxQueryPages)
}
func (c *Client) CreatePage(ctx context.Context, dataSourceID string, properties map[string]interface{}) (*Page, error) {
request := map[string]interface{}{
"parent": map[string]interface{}{
"type": "data_source_id",
"data_source_id": dataSourceID,
},
"properties": properties,
}
body, err := c.doRequest(ctx, http.MethodPost, "/pages", request)
if err != nil {
return nil, err
}
var page Page
if err := json.Unmarshal(body, &page); err != nil {
return nil, fmt.Errorf("parse create page response: %w", err)
}
return &page, nil
}
func (c *Client) UpdatePage(ctx context.Context, pageID string, properties map[string]interface{}) (*Page, error) {
request := map[string]interface{}{"properties": properties}
body, err := c.doRequest(ctx, http.MethodPatch, "/pages/"+url.PathEscape(pageID), request)
if err != nil {
return nil, err
}
var page Page
if err := json.Unmarshal(body, &page); err != nil {
return nil, fmt.Errorf("parse update page response: %w", err)
}
return &page, nil
}
func (c *Client) ArchivePage(ctx context.Context, pageID string, inTrash bool) (*Page, error) {
body, err := c.doRequest(ctx, http.MethodPatch, "/pages/"+url.PathEscape(pageID), map[string]interface{}{"in_trash": inTrash})
if err != nil {
return nil, err
}
var page Page
if err := json.Unmarshal(body, &page); err != nil {
return nil, fmt.Errorf("parse archive page response: %w", err)
}
return &page, nil
}
type DataSourceResolver interface {
RetrieveDataSource(ctx context.Context, dataSourceID string) (*DataSource, error)
RetrieveDatabase(ctx context.Context, databaseID string) (*Database, error)
}
type ResolvedDataSource struct {
InputID string
DataSourceID string
DataSource *DataSource
Database *Database
ViewURL string
}
func ResolveDataSourceReference(ctx context.Context, client DataSourceResolver, ref string) (*ResolvedDataSource, error) {
if client == nil {
return nil, fmt.Errorf("notion client is nil")
}
identifier := ExtractNotionIdentifier(ref)
if identifier == "" {
return nil, fmt.Errorf("could not extract a Notion ID from %q", ref)
}
if ds, err := client.RetrieveDataSource(ctx, identifier); err == nil {
return &ResolvedDataSource{
InputID: identifier,
DataSourceID: ds.ID,
DataSource: ds,
ViewURL: strings.TrimSpace(ref),
}, nil
} else {
db, dbErr := client.RetrieveDatabase(ctx, identifier)
if dbErr != nil {
return nil, fmt.Errorf("resolve %q as data source: %w; as database: %v", ref, err, dbErr)
}
if len(db.DataSources) == 0 || strings.TrimSpace(db.DataSources[0].ID) == "" {
return nil, fmt.Errorf("database %s has no child data sources", db.ID)
}
resolvedID := strings.TrimSpace(db.DataSources[0].ID)
resolvedDS, err := client.RetrieveDataSource(ctx, resolvedID)
if err != nil {
return nil, fmt.Errorf("retrieve child data source %s: %w", resolvedID, err)
}
return &ResolvedDataSource{
InputID: identifier,
DataSourceID: resolvedID,
DataSource: resolvedDS,
Database: db,
ViewURL: strings.TrimSpace(ref),
}, nil
}
}
func (c *Client) doRequest(ctx context.Context, method, path string, requestBody interface{}) ([]byte, error) {
if c == nil {
return nil, fmt.Errorf("notion client is nil")
}
if strings.TrimSpace(c.Token) == "" {
return nil, fmt.Errorf("Notion token not configured")
}
httpClient := c.HTTPClient
if httpClient == nil {
httpClient = &http.Client{Timeout: DefaultTimeout}
}
var bodyReader io.Reader
if requestBody != nil {
payload, err := json.Marshal(requestBody)
if err != nil {
return nil, fmt.Errorf("marshal request body: %w", err)
}
bodyReader = bytes.NewReader(payload)
}
requestURL := path
if !strings.HasPrefix(requestURL, "http://") && !strings.HasPrefix(requestURL, "https://") {
requestURL = strings.TrimSuffix(c.BaseURL, "/") + path
}
req, err := http.NewRequestWithContext(ctx, method, requestURL, bodyReader)
if err != nil {
return nil, fmt.Errorf("create request: %w", err)
}
req.Header.Set("Authorization", "Bearer "+c.Token)
req.Header.Set("Notion-Version", c.NotionVersion)
req.Header.Set("Accept", "application/json")
if requestBody != nil {
req.Header.Set("Content-Type", "application/json")
}
resp, err := httpClient.Do(req) //nolint:gosec // G704: URL is constructed from configured Notion API base, not user input
if err != nil {
return nil, fmt.Errorf("request failed: %w", err)
}
defer func() { _ = resp.Body.Close() }()
body, err := io.ReadAll(io.LimitReader(resp.Body, maxResponseBytes))
if err != nil {
return nil, fmt.Errorf("read response: %w", err)
}
if resp.StatusCode >= 200 && resp.StatusCode < 300 {
return body, nil
}
var apiErr struct {
Code string `json:"code"`
Message string `json:"message"`
}
if err := json.Unmarshal(body, &apiErr); err == nil && apiErr.Message != "" {
return nil, fmt.Errorf("Notion API error %s (%d): %s", apiErr.Code, resp.StatusCode, apiErr.Message)
}
return nil, fmt.Errorf("Notion API error (%d): %s", resp.StatusCode, strings.TrimSpace(string(body)))
}

View file

@ -0,0 +1,224 @@
package notion
import (
"context"
"io"
"net/http"
"net/http/httptest"
"strings"
"testing"
)
func TestClientRetrieveDataSourceSetsHeaders(t *testing.T) {
t.Parallel()
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/data_sources/ds_123" {
t.Fatalf("path = %q", r.URL.Path)
}
if got := r.Header.Get("Authorization"); got != "Bearer secret-token" {
t.Fatalf("authorization = %q", got)
}
if got := r.Header.Get("Notion-Version"); got != DefaultNotionVersion {
t.Fatalf("notion version = %q", got)
}
_, _ = io.WriteString(w, `{"id":"ds_123","url":"https://www.notion.so/source","title":[{"plain_text":"Tasks"}],"properties":{"Name":{"type":"title"}}}`)
}))
defer server.Close()
client := NewClient("secret-token").WithBaseURL(server.URL)
ds, err := client.RetrieveDataSource(context.Background(), "ds_123")
if err != nil {
t.Fatalf("RetrieveDataSource returned error: %v", err)
}
if ds.ID != "ds_123" {
t.Fatalf("id = %q", ds.ID)
}
if DataSourceTitle(ds.Title) != "Tasks" {
t.Fatalf("title = %q", DataSourceTitle(ds.Title))
}
}
func TestClientQueryDataSourcePaginates(t *testing.T) {
t.Parallel()
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
_, _ = io.ReadAll(r.Body)
switch r.Header.Get("X-Test-Step") {
default:
}
if r.URL.Path != "/data_sources/ds_123/query" {
t.Fatalf("path = %q", r.URL.Path)
}
if !strings.Contains(r.Header.Get("Content-Type"), "application/json") {
t.Fatalf("content type = %q", r.Header.Get("Content-Type"))
}
if !strings.Contains(r.URL.RawQuery, "") {
}
if strings.Contains(r.Header.Get("X-Page"), "2") {
}
}))
defer server.Close()
call := 0
server.Config.Handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
call++
body, _ := io.ReadAll(r.Body)
if r.URL.Path != "/data_sources/ds_123/query" {
t.Fatalf("path = %q", r.URL.Path)
}
if call == 1 {
if !strings.Contains(string(body), `"page_size":100`) {
t.Fatalf("request body = %s", body)
}
_, _ = io.WriteString(w, `{"results":[{"id":"page-1"},{"id":"page-2"}],"has_more":true,"next_cursor":"cursor-2"}`)
return
}
if !strings.Contains(string(body), `"start_cursor":"cursor-2"`) {
t.Fatalf("request body = %s", body)
}
_, _ = io.WriteString(w, `{"results":[{"id":"page-3"}],"has_more":false}`)
})
client := NewClient("secret-token").WithBaseURL(server.URL)
pages, err := client.QueryDataSource(context.Background(), "ds_123")
if err != nil {
t.Fatalf("QueryDataSource returned error: %v", err)
}
if len(pages) != 3 {
t.Fatalf("pages = %d, want 3", len(pages))
}
}
func TestClientReturnsStructuredAPIError(t *testing.T) {
t.Parallel()
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusUnauthorized)
_, _ = io.WriteString(w, `{"code":"unauthorized","message":"token is invalid"}`)
}))
defer server.Close()
client := NewClient("secret-token").WithBaseURL(server.URL)
_, err := client.GetCurrentUser(context.Background())
if err == nil {
t.Fatal("expected error, got nil")
}
if !strings.Contains(err.Error(), "token is invalid") {
t.Fatalf("error = %q", err)
}
}
func TestClientCreateDatabaseSendsInitialDataSource(t *testing.T) {
t.Parallel()
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/databases" {
t.Fatalf("path = %q", r.URL.Path)
}
body, _ := io.ReadAll(r.Body)
for _, want := range []string{
`"page_id":"329e5bf9-7fae-8080-bb4a-d94e1387655d"`,
`"initial_data_source"`,
`"Beads ID"`,
`"Status"`,
`"Type"`,
} {
if !strings.Contains(string(body), want) {
t.Fatalf("request body missing %q\n%s", want, body)
}
}
_, _ = io.WriteString(w, `{"id":"db_123","url":"https://www.notion.so/db123","data_sources":[{"id":"ds_123","name":"Beads Issues"}]}`)
}))
defer server.Close()
client := NewClient("secret-token").WithBaseURL(server.URL)
db, err := client.CreateDatabase(context.Background(), "329e5bf9-7fae-8080-bb4a-d94e1387655d", DefaultDatabaseTitle)
if err != nil {
t.Fatalf("CreateDatabase returned error: %v", err)
}
if db.ID != "db_123" {
t.Fatalf("id = %q", db.ID)
}
if len(db.DataSources) != 1 || db.DataSources[0].ID != "ds_123" {
t.Fatalf("data_sources = %+v", db.DataSources)
}
}
func TestClientRetrieveDatabase(t *testing.T) {
t.Parallel()
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/databases/db_123" {
t.Fatalf("path = %q", r.URL.Path)
}
_, _ = io.WriteString(w, `{"id":"db_123","url":"https://www.notion.so/db123","data_sources":[{"id":"ds_123","name":"Beads Issues"}]}`)
}))
defer server.Close()
client := NewClient("secret-token").WithBaseURL(server.URL)
db, err := client.RetrieveDatabase(context.Background(), "db_123")
if err != nil {
t.Fatalf("RetrieveDatabase returned error: %v", err)
}
if db.ID != "db_123" {
t.Fatalf("id = %q", db.ID)
}
if len(db.DataSources) != 1 || db.DataSources[0].ID != "ds_123" {
t.Fatalf("data_sources = %+v", db.DataSources)
}
}
func TestResolveDataSourceReferencePrefersDataSource(t *testing.T) {
t.Parallel()
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case "/data_sources/329e5bf9-7fae-8080-bb4a-d94e1387655d":
_, _ = io.WriteString(w, `{"id":"329e5bf9-7fae-8080-bb4a-d94e1387655d","properties":{"Name":{"type":"title"}}}`)
default:
t.Fatalf("path = %q", r.URL.Path)
}
}))
defer server.Close()
client := NewClient("secret-token").WithBaseURL(server.URL)
resolved, err := ResolveDataSourceReference(context.Background(), client, "https://www.notion.so/workspace/329e5bf97fae8080bb4ad94e1387655d")
if err != nil {
t.Fatalf("ResolveDataSourceReference returned error: %v", err)
}
if resolved.DataSourceID != "329e5bf9-7fae-8080-bb4a-d94e1387655d" {
t.Fatalf("data_source_id = %q", resolved.DataSourceID)
}
}
func TestResolveDataSourceReferenceFallsBackToDatabase(t *testing.T) {
t.Parallel()
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case "/data_sources/429e5bf9-7fae-8080-bb4a-d94e1387655d":
w.WriteHeader(http.StatusNotFound)
_, _ = io.WriteString(w, `{"code":"object_not_found","message":"not found"}`)
case "/databases/429e5bf9-7fae-8080-bb4a-d94e1387655d":
_, _ = io.WriteString(w, `{"id":"429e5bf9-7fae-8080-bb4a-d94e1387655d","data_sources":[{"id":"529e5bf9-7fae-8080-bb4a-d94e1387655d","name":"Beads Issues"}]}`)
case "/data_sources/529e5bf9-7fae-8080-bb4a-d94e1387655d":
_, _ = io.WriteString(w, `{"id":"529e5bf9-7fae-8080-bb4a-d94e1387655d","properties":{"Name":{"type":"title"}}}`)
default:
t.Fatalf("path = %q", r.URL.Path)
}
}))
defer server.Close()
client := NewClient("secret-token").WithBaseURL(server.URL)
resolved, err := ResolveDataSourceReference(context.Background(), client, "https://www.notion.so/workspace/429e5bf97fae8080bb4ad94e1387655d")
if err != nil {
t.Fatalf("ResolveDataSourceReference returned error: %v", err)
}
if resolved.DataSourceID != "529e5bf9-7fae-8080-bb4a-d94e1387655d" {
t.Fatalf("data_source_id = %q", resolved.DataSourceID)
}
if resolved.Database == nil || resolved.Database.ID != "429e5bf9-7fae-8080-bb4a-d94e1387655d" {
t.Fatalf("database = %+v", resolved.Database)
}
}

View file

@ -0,0 +1,97 @@
package notion
import (
"github.com/steveyegge/beads/internal/tracker"
"github.com/steveyegge/beads/internal/types"
)
// FieldMapper implements tracker.FieldMapper for Notion.
type FieldMapper struct {
config *MappingConfig
}
// NewFieldMapper constructs a Notion field mapper with the default mapping when config is nil.
func NewFieldMapper(config *MappingConfig) *FieldMapper {
if config == nil {
config = DefaultMappingConfig()
}
return &FieldMapper{config: config}
}
func (m *FieldMapper) PriorityToBeads(trackerPriority interface{}) int {
value, ok := trackerPriority.(string)
if !ok {
return 2
}
return priorityToBeads(value, m.config)
}
func (m *FieldMapper) PriorityToTracker(beadsPriority int) interface{} {
return priorityToNotion(beadsPriority, m.config)
}
func (m *FieldMapper) StatusToBeads(trackerState interface{}) types.Status {
value, ok := trackerState.(string)
if !ok {
return types.StatusOpen
}
return statusToBeads(value, m.config)
}
func (m *FieldMapper) StatusToTracker(beadsStatus types.Status) interface{} {
return statusToNotion(beadsStatus, m.config)
}
func (m *FieldMapper) TypeToBeads(trackerType interface{}) types.IssueType {
value, ok := trackerType.(string)
if !ok {
return types.TypeTask
}
return typeToBeads(value, m.config)
}
func (m *FieldMapper) TypeToTracker(beadsType types.IssueType) interface{} {
return typeToNotion(beadsType, m.config)
}
func (m *FieldMapper) IssueToBeads(ti *tracker.TrackerIssue) *tracker.IssueConversion {
if ti == nil {
return nil
}
switch raw := ti.Raw.(type) {
case *PulledIssue:
issue, err := BeadsIssueFromPullIssue(*raw, m.config)
if err != nil {
return nil
}
return &tracker.IssueConversion{Issue: issue}
case PulledIssue:
issue, err := BeadsIssueFromPullIssue(raw, m.config)
if err != nil {
return nil
}
return &tracker.IssueConversion{Issue: issue}
default:
return nil
}
}
func (m *FieldMapper) IssueToTracker(issue *types.Issue) map[string]interface{} {
pushIssue, err := PushIssueFromIssue(issue, m.config)
if err != nil {
return map[string]interface{}{}
}
return map[string]interface{}{
"id": pushIssue.ID,
"title": pushIssue.Title,
"description": pushIssue.Description,
"status": pushIssue.Status,
"priority": pushIssue.Priority,
"issue_type": pushIssue.IssueType,
"assignee": pushIssue.Assignee,
"labels": pushIssue.Labels,
"external_ref": pushIssue.ExternalRef,
}
}

365
internal/notion/mapping.go Normal file
View file

@ -0,0 +1,365 @@
package notion
import (
"fmt"
"sort"
"strings"
"time"
"github.com/steveyegge/beads/internal/tracker"
"github.com/steveyegge/beads/internal/types"
)
// MappingConfig defines fixed conversions between Notion sync payloads and beads core types.
type MappingConfig struct {
PriorityToBeads map[string]int
PriorityToNotion map[int]string
StatusToBeads map[string]types.Status
StatusToNotion map[types.Status]string
TypeToBeads map[string]types.IssueType
TypeToNotion map[types.IssueType]string
}
// DefaultMappingConfig returns the v1 fixed mapping for the dedicated Notion beads schema.
func DefaultMappingConfig() *MappingConfig {
return &MappingConfig{
PriorityToBeads: map[string]int{
"critical": 0,
"high": 1,
"medium": 2,
"low": 3,
"backlog": 4,
},
PriorityToNotion: map[int]string{
0: "Critical",
1: "High",
2: "Medium",
3: "Low",
4: "Backlog",
},
StatusToBeads: map[string]types.Status{
"open": types.StatusOpen,
"in_progress": types.StatusInProgress,
"blocked": types.StatusBlocked,
"deferred": types.StatusDeferred,
"closed": types.StatusClosed,
},
StatusToNotion: map[types.Status]string{
types.StatusOpen: "Open",
types.StatusInProgress: "In Progress",
types.StatusBlocked: "Blocked",
types.StatusDeferred: "Deferred",
types.StatusClosed: "Closed",
},
TypeToBeads: map[string]types.IssueType{
"bug": types.TypeBug,
"feature": types.TypeFeature,
"task": types.TypeTask,
"epic": types.TypeEpic,
"chore": types.TypeChore,
},
TypeToNotion: map[types.IssueType]string{
types.TypeBug: "Bug",
types.TypeFeature: "Feature",
types.TypeTask: "Task",
types.TypeEpic: "Epic",
types.TypeChore: "Chore",
},
}
}
// BeadsIssueFromPullIssue converts one pulled Notion issue into a beads core issue.
func BeadsIssueFromPullIssue(issue PulledIssue, config *MappingConfig) (*types.Issue, error) {
if config == nil {
config = DefaultMappingConfig()
}
status := statusToBeads(issue.Status, config)
priority := priorityToBeads(issue.Priority, config)
issueTypeRaw := issue.IssueType
if strings.TrimSpace(issueTypeRaw) == "" {
issueTypeRaw = issue.Type
}
issueType := typeToBeads(issueTypeRaw, config)
createdAt, hasCreated, err := parseMappingTimestamp(string(issue.CreatedAt))
if err != nil {
return nil, fmt.Errorf("parse created_at: %w", err)
}
updatedAt, hasUpdated, err := parseMappingTimestamp(string(issue.UpdatedAt))
if err != nil {
return nil, fmt.Errorf("parse updated_at: %w", err)
}
now := time.Now().UTC()
if !hasCreated {
createdAt = now
}
if !hasUpdated {
updatedAt = createdAt
}
beadsIssue := &types.Issue{
ID: strings.TrimSpace(issue.ID),
Title: strings.TrimSpace(issue.Title),
Description: strings.TrimSpace(issue.Description),
Status: status,
Priority: priority,
IssueType: issueType,
Assignee: issue.Assignee,
Labels: append([]string(nil), issue.Labels...),
SourceSystem: "notion",
CreatedAt: createdAt,
UpdatedAt: updatedAt,
}
if externalRef := BuildNotionExternalRef(&issue); externalRef != "" {
beadsIssue.ExternalRef = &externalRef
}
return beadsIssue, nil
}
// TrackerIssueFromPullIssue converts a pull issue to the generic tracker representation.
func TrackerIssueFromPullIssue(issue PulledIssue, config *MappingConfig) (*tracker.TrackerIssue, error) {
beadsIssue, err := BeadsIssueFromPullIssue(issue, config)
if err != nil {
return nil, err
}
url := strings.TrimSpace(issue.ExternalRef)
if canonical, ok := CanonicalizeNotionPageURL(url); ok {
url = canonical
}
if url == "" {
url = notionPageURL(firstNonEmpty(issue.NotionPageID, issue.ID))
}
trackerIssue := &tracker.TrackerIssue{
ID: issue.NotionPageID,
Identifier: ExtractNotionIdentifier(firstNonEmpty(url, issue.NotionPageID)),
URL: url,
Title: beadsIssue.Title,
Description: beadsIssue.Description,
Priority: beadsIssue.Priority,
State: beadsIssue.Status,
Type: beadsIssue.IssueType,
Labels: append([]string(nil), beadsIssue.Labels...),
Assignee: beadsIssue.Assignee,
CreatedAt: beadsIssue.CreatedAt,
UpdatedAt: beadsIssue.UpdatedAt,
Raw: &issue,
}
return trackerIssue, nil
}
// PushIssueFromIssue converts one beads issue into the Notion push issue shape.
func PushIssueFromIssue(issue *types.Issue, config *MappingConfig) (*PushIssue, error) {
if issue == nil {
return nil, fmt.Errorf("issue is nil")
}
if config == nil {
config = DefaultMappingConfig()
}
if !SupportsIssueType(issue.IssueType, config) {
return nil, fmt.Errorf("unsupported Notion issue type %q", issue.IssueType)
}
status := statusToNotion(issue.Status, config)
priority := priorityToNotion(issue.Priority, config)
issueType := typeToNotion(issue.IssueType, config)
pushIssue := &PushIssue{
ID: issue.ID,
Title: issue.Title,
Description: issue.Description,
Status: status,
Priority: priority,
IssueType: issueType,
Assignee: issue.Assignee,
Labels: append([]string(nil), issue.Labels...),
}
if issue.ExternalRef != nil && strings.TrimSpace(*issue.ExternalRef) != "" {
if canonical, ok := CanonicalizeNotionExternalRef(*issue.ExternalRef); ok {
pushIssue.ExternalRef = canonical
}
}
return pushIssue, nil
}
func BuildPageProperties(pushIssue *PushIssue) map[string]interface{} {
labels := make([]map[string]interface{}, 0, len(pushIssue.Labels))
for _, label := range pushIssue.Labels {
label = strings.TrimSpace(label)
if label == "" {
continue
}
labels = append(labels, map[string]interface{}{"name": label})
}
return map[string]interface{}{
PropertyTitle: map[string]interface{}{"title": richTextRequest(pushIssue.Title)},
PropertyBeadsID: map[string]interface{}{"rich_text": richTextRequest(pushIssue.ID)},
PropertyStatus: map[string]interface{}{"select": map[string]interface{}{"name": pushIssue.Status}},
PropertyPriority: map[string]interface{}{"select": map[string]interface{}{"name": pushIssue.Priority}},
PropertyType: map[string]interface{}{"select": map[string]interface{}{"name": pushIssue.IssueType}},
PropertyDescription: map[string]interface{}{"rich_text": richTextRequest(pushIssue.Description)},
PropertyAssignee: map[string]interface{}{"rich_text": richTextRequest(pushIssue.Assignee)},
PropertyLabels: map[string]interface{}{"multi_select": labels},
}
}
func PulledIssueFromPage(page Page) PulledIssue {
issue := PulledIssue{
ID: strings.TrimSpace(DataSourceTitle(page.Properties[PropertyBeadsID].RichText)),
Title: strings.TrimSpace(DataSourceTitle(page.Properties[PropertyTitle].Title)),
Description: strings.TrimSpace(DataSourceTitle(page.Properties[PropertyDescription].RichText)),
Status: strings.TrimSpace(pagePropertySelect(page.Properties[PropertyStatus])),
Priority: strings.TrimSpace(pagePropertySelect(page.Properties[PropertyPriority])),
Type: strings.TrimSpace(pagePropertySelect(page.Properties[PropertyType])),
IssueType: strings.TrimSpace(pagePropertySelect(page.Properties[PropertyType])),
Assignee: strings.TrimSpace(DataSourceTitle(page.Properties[PropertyAssignee].RichText)),
Labels: pagePropertyMultiSelect(page.Properties[PropertyLabels]),
ExternalRef: strings.TrimSpace(page.URL),
NotionPageID: strings.TrimSpace(page.ID),
CreatedAt: NullableString(page.CreatedTime.UTC().Format(time.RFC3339)),
UpdatedAt: NullableString(page.LastEditedTime.UTC().Format(time.RFC3339)),
}
if externalRef := BuildNotionExternalRef(&issue); externalRef != "" {
issue.ExternalRef = externalRef
}
return issue
}
func ValidateDataSourceSchema(ds *DataSource) *StatusSchema {
result := &StatusSchema{Checked: true}
for name := range requiredSchemaProperties {
result.Required = append(result.Required, name)
}
sort.Strings(result.Required)
if ds == nil {
result.Missing = append([]string(nil), result.Required...)
return result
}
for name := range ds.Properties {
result.Detected = append(result.Detected, name)
}
sort.Strings(result.Detected)
for _, name := range result.Required {
property, ok := ds.Properties[name]
if !ok || property.Type != requiredSchemaProperties[name] {
result.Missing = append(result.Missing, name)
}
}
return result
}
func priorityToBeads(raw string, config *MappingConfig) int {
value, ok := config.PriorityToBeads[normalizeMappingValue(raw)]
if !ok {
return 2
}
return value
}
func priorityToNotion(priority int, config *MappingConfig) string {
value, ok := config.PriorityToNotion[priority]
if !ok {
return "Medium"
}
return value
}
func statusToBeads(raw string, config *MappingConfig) types.Status {
value, ok := config.StatusToBeads[normalizeMappingValue(raw)]
if !ok {
return types.StatusOpen
}
return value
}
func statusToNotion(status types.Status, config *MappingConfig) string {
value, ok := config.StatusToNotion[status]
if !ok {
return "Open"
}
return value
}
func typeToBeads(raw string, config *MappingConfig) types.IssueType {
value, ok := config.TypeToBeads[normalizeMappingValue(raw)]
if !ok {
return types.TypeTask
}
return value
}
func typeToNotion(issueType types.IssueType, config *MappingConfig) string {
trimmed := strings.TrimSpace(string(issueType))
if trimmed == "" {
return "Task"
}
value, ok := config.TypeToNotion[issueType]
if !ok {
return "Task"
}
return value
}
func SupportsIssueType(issueType types.IssueType, config *MappingConfig) bool {
if config == nil {
config = DefaultMappingConfig()
}
_, ok := config.TypeToNotion[issueType]
return ok
}
func parseMappingTimestamp(raw string) (time.Time, bool, error) {
if strings.TrimSpace(raw) == "" {
return time.Time{}, false, nil
}
parsed, err := time.Parse(time.RFC3339Nano, raw)
if err == nil {
return parsed, true, nil
}
parsed, err = time.Parse(time.RFC3339, raw)
if err != nil {
return time.Time{}, false, err
}
return parsed, true, nil
}
func normalizeMappingValue(value string) string {
value = strings.TrimSpace(strings.ToLower(value))
value = strings.ReplaceAll(value, " ", "_")
value = strings.ReplaceAll(value, "-", "_")
return value
}
func pagePropertySelect(prop PageProperty) string {
if prop.Select == nil {
return ""
}
return prop.Select.Name
}
func pagePropertyMultiSelect(prop PageProperty) []string {
labels := make([]string, 0, len(prop.MultiSelect))
for _, item := range prop.MultiSelect {
name := strings.TrimSpace(item.Name)
if name != "" {
labels = append(labels, name)
}
}
return labels
}
func firstNonEmpty(values ...string) string {
for _, value := range values {
if strings.TrimSpace(value) != "" {
return strings.TrimSpace(value)
}
}
return ""
}

View file

@ -0,0 +1,167 @@
package notion
import (
"testing"
"time"
"github.com/steveyegge/beads/internal/types"
)
func TestBuildPagePropertiesAndPulledIssueRoundTrip(t *testing.T) {
t.Parallel()
externalRef := "https://www.notion.so/Task-0123456789abcdef0123456789abcdef"
issue := &types.Issue{
ID: "bd-123",
Title: "Sync from Notion",
Description: "Short summary",
Status: types.StatusInProgress,
Priority: 1,
IssueType: types.TypeFeature,
Assignee: "osamu",
Labels: []string{"sync", "notion"},
ExternalRef: &externalRef,
}
pushIssue, err := PushIssueFromIssue(issue, nil)
if err != nil {
t.Fatalf("PushIssueFromIssue returned error: %v", err)
}
if pushIssue.Status != "In Progress" {
t.Fatalf("status = %q, want %q", pushIssue.Status, "In Progress")
}
if pushIssue.ExternalRef != "https://www.notion.so/0123456789abcdef0123456789abcdef" {
t.Fatalf("external_ref = %q", pushIssue.ExternalRef)
}
if len(pushIssue.Labels) != 2 {
t.Fatalf("push labels = %v, want 2 labels", pushIssue.Labels)
}
properties := BuildPageProperties(pushIssue)
statusProp, ok := properties[PropertyStatus].(map[string]interface{})
if !ok {
t.Fatalf("status property type = %T", properties[PropertyStatus])
}
selectProp, ok := statusProp["select"].(map[string]interface{})
if !ok || selectProp["name"] != "In Progress" {
t.Fatalf("status select = %#v", statusProp["select"])
}
labelsProp, ok := properties[PropertyLabels].(map[string]interface{})
if !ok {
t.Fatalf("labels property type = %T", properties[PropertyLabels])
}
multiSelect, ok := labelsProp["multi_select"].([]map[string]interface{})
if !ok || len(multiSelect) != 2 {
t.Fatalf("labels multi_select = %#v", labelsProp["multi_select"])
}
createdAt := time.Date(2026, 3, 19, 14, 0, 0, 0, time.UTC)
updatedAt := createdAt.Add(5 * time.Minute)
page := Page{
ID: "01234567-89ab-cdef-0123-456789abcdef",
URL: "https://www.notion.so/Task-0123456789abcdef0123456789abcdef?pvs=4",
CreatedTime: createdAt,
LastEditedTime: updatedAt,
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Sync from Notion"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-123"}}},
PropertyStatus: {Select: &SelectOption{Name: "In Progress"}},
PropertyPriority: {Select: &SelectOption{Name: "High"}},
PropertyType: {Select: &SelectOption{Name: "Feature"}},
PropertyDescription: {RichText: []RichText{{PlainText: "Short summary"}}},
PropertyAssignee: {RichText: []RichText{{PlainText: "osamu"}}},
PropertyLabels: {MultiSelect: []SelectOption{{Name: "sync"}, {Name: "notion"}}},
},
}
pulled := PulledIssueFromPage(page)
if pulled.ExternalRef != "https://www.notion.so/0123456789abcdef0123456789abcdef" {
t.Fatalf("external ref = %q", pulled.ExternalRef)
}
beadsIssue, err := BeadsIssueFromPullIssue(pulled, nil)
if err != nil {
t.Fatalf("BeadsIssueFromPullIssue returned error: %v", err)
}
if beadsIssue.Status != types.StatusInProgress {
t.Fatalf("status = %q, want %q", beadsIssue.Status, types.StatusInProgress)
}
if beadsIssue.Priority != 1 {
t.Fatalf("priority = %d, want 1", beadsIssue.Priority)
}
if beadsIssue.IssueType != types.TypeFeature {
t.Fatalf("issue type = %q, want %q", beadsIssue.IssueType, types.TypeFeature)
}
if len(beadsIssue.Labels) != 2 {
t.Fatalf("labels = %v, want 2 labels", beadsIssue.Labels)
}
}
func TestValidateDataSourceSchema(t *testing.T) {
t.Parallel()
ds := &DataSource{
Properties: map[string]DataSourceProperty{
PropertyTitle: {Type: "title"},
PropertyBeadsID: {Type: "rich_text"},
PropertyStatus: {Type: "select"},
PropertyPriority: {Type: "select"},
PropertyType: {Type: "select"},
PropertyDescription: {Type: "rich_text"},
PropertyAssignee: {Type: "rich_text"},
},
}
schema := ValidateDataSourceSchema(ds)
if !schema.Checked {
t.Fatal("expected schema to be checked")
}
if len(schema.Missing) != 1 || schema.Missing[0] != PropertyLabels {
t.Fatalf("missing = %v, want [%q]", schema.Missing, PropertyLabels)
}
}
func TestValidateDataSourceSchemaMatchesInitSchema(t *testing.T) {
t.Parallel()
properties := BuildInitialDataSourceProperties()
ds := &DataSource{Properties: map[string]DataSourceProperty{}}
for name, raw := range properties {
property, ok := raw.(map[string]interface{})
if !ok {
t.Fatalf("property %q type = %T", name, raw)
}
for key := range property {
if key == "type" {
continue
}
ds.Properties[name] = DataSourceProperty{Type: key}
break
}
}
schema := ValidateDataSourceSchema(ds)
if len(schema.Missing) != 0 {
t.Fatalf("missing = %v", schema.Missing)
}
}
func TestPushIssueFromIssueRejectsUnsupportedIssueType(t *testing.T) {
t.Parallel()
issue := &types.Issue{
ID: "bd-event-1",
Title: "State change: progress -> in_progress",
Status: types.StatusOpen,
Priority: 2,
IssueType: types.TypeEvent,
}
if SupportsIssueType(issue.IssueType, nil) {
t.Fatal("expected event to be unsupported for Notion schema")
}
if _, err := PushIssueFromIssue(issue, nil); err == nil {
t.Fatal("expected unsupported issue type error")
}
}

118
internal/notion/refs.go Normal file
View file

@ -0,0 +1,118 @@
package notion
import (
"fmt"
"net/url"
"regexp"
"strings"
)
var notionPageIDPattern = regexp.MustCompile("(?i)[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}")
// IsNotionExternalRef reports whether ref can be resolved to a Notion page.
func IsNotionExternalRef(ref string) bool {
_, ok := CanonicalizeNotionExternalRef(ref)
return ok
}
// CanonicalizeNotionExternalRef normalizes supported Notion page URLs to a stable external ref.
func CanonicalizeNotionExternalRef(ref string) (string, bool) {
ref = strings.TrimSpace(ref)
if ref == "" {
return "", false
}
parsed, err := url.Parse(ref)
if err != nil {
return "", false
}
host := strings.ToLower(parsed.Host)
if host != "www.notion.so" && host != "notion.so" {
return "", false
}
pageID := extractNotionPageID(parsed.Path)
if pageID == "" {
return "", false
}
return notionPageURL(pageID), true
}
// CanonicalizeNotionPageURL normalizes a supported Notion page URL or page id to a canonical page URL.
func CanonicalizeNotionPageURL(ref string) (string, bool) {
pageID := ExtractNotionIdentifier(ref)
if pageID == "" {
return "", false
}
return notionPageURL(pageID), true
}
// ExtractNotionIdentifier returns the normalized hyphenated page id.
func ExtractNotionIdentifier(ref string) string {
ref = strings.TrimSpace(ref)
if normalized, ok := normalizeNotionPageID(ref); ok {
return normalized
}
parsed, err := url.Parse(ref)
if err != nil {
return ""
}
return extractNotionPageID(parsed.Path)
}
// BuildNotionExternalRef chooses the canonical external ref for a pulled issue.
func BuildNotionExternalRef(issue *PulledIssue) string {
if issue == nil {
return ""
}
if canonical, ok := CanonicalizeNotionPageURL(issue.ExternalRef); ok {
return canonical
}
if canonical, ok := CanonicalizeNotionPageURL(issue.NotionPageID); ok {
return canonical
}
if canonical, ok := CanonicalizeNotionExternalRef(issue.ExternalRef); ok {
return canonical
}
return ""
}
func notionPageURL(pageID string) string {
return fmt.Sprintf("https://www.notion.so/%s", compactNotionPageID(pageID))
}
func extractNotionPageID(path string) string {
match := notionPageIDPattern.FindString(path)
if match == "" {
return ""
}
normalized, ok := normalizeNotionPageID(match)
if !ok {
return ""
}
return normalized
}
func normalizeNotionPageID(value string) (string, bool) {
cleaned := strings.ToLower(strings.ReplaceAll(strings.TrimSpace(value), "-", ""))
if len(cleaned) != 32 {
return "", false
}
for _, r := range cleaned {
if (r < '0' || r > '9') && (r < 'a' || r > 'f') {
return "", false
}
}
return fmt.Sprintf("%s-%s-%s-%s-%s",
cleaned[0:8],
cleaned[8:12],
cleaned[12:16],
cleaned[16:20],
cleaned[20:32],
), true
}
func compactNotionPageID(pageID string) string {
return strings.ReplaceAll(pageID, "-", "")
}

View file

@ -0,0 +1,113 @@
package notion
import "testing"
func TestCanonicalizeNotionExternalRef(t *testing.T) {
t.Parallel()
tests := []struct {
name string
ref string
want string
ok bool
}{
{
name: "canonical url",
ref: "https://www.notion.so/My-Page-0123456789abcdef0123456789abcdef?pvs=4",
want: "https://www.notion.so/0123456789abcdef0123456789abcdef",
ok: true,
},
{
name: "bare page id rejected",
ref: "0123456789abcdef0123456789abcdef",
ok: false,
},
{
name: "not notion",
ref: "https://example.com/item/1",
ok: false,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got, ok := CanonicalizeNotionExternalRef(tt.ref)
if ok != tt.ok {
t.Fatalf("ok = %v, want %v", ok, tt.ok)
}
if got != tt.want {
t.Fatalf("got = %q, want %q", got, tt.want)
}
})
}
}
func TestExtractNotionIdentifier(t *testing.T) {
t.Parallel()
tests := []struct {
ref string
want string
}{
{
ref: "https://www.notion.so/My-Page-0123456789abcdef0123456789abcdef",
want: "01234567-89ab-cdef-0123-456789abcdef",
},
{
ref: "0123456789abcdef0123456789abcdef",
want: "01234567-89ab-cdef-0123-456789abcdef",
},
}
for _, tt := range tests {
if got := ExtractNotionIdentifier(tt.ref); got != tt.want {
t.Fatalf("ExtractNotionIdentifier(%q) = %q, want %q", tt.ref, got, tt.want)
}
}
}
func TestBuildNotionExternalRefPrefersURL(t *testing.T) {
t.Parallel()
issue := &PulledIssue{
ExternalRef: "https://www.notion.so/Test-0123456789abcdef0123456789abcdef",
NotionPageID: "fedcba98-7654-3210-fedc-ba9876543210",
}
got := BuildNotionExternalRef(issue)
want := "https://www.notion.so/0123456789abcdef0123456789abcdef"
if got != want {
t.Fatalf("got = %q, want %q", got, want)
}
}
func TestCanonicalizeNotionPageURL(t *testing.T) {
t.Parallel()
for _, tt := range []struct {
name string
ref string
want string
}{
{
name: "url",
ref: "https://www.notion.so/Test-0123456789abcdef0123456789abcdef",
want: "https://www.notion.so/0123456789abcdef0123456789abcdef",
},
{
name: "bare id",
ref: "01234567-89ab-cdef-0123-456789abcdef",
want: "https://www.notion.so/0123456789abcdef0123456789abcdef",
},
} {
t.Run(tt.name, func(t *testing.T) {
got, ok := CanonicalizeNotionPageURL(tt.ref)
if !ok {
t.Fatal("expected ok, got false")
}
if got != tt.want {
t.Fatalf("got = %q, want %q", got, tt.want)
}
})
}
}

674
internal/notion/tracker.go Normal file
View file

@ -0,0 +1,674 @@
package notion
import (
"context"
"fmt"
"os"
"sort"
"strings"
"sync"
"time"
"github.com/steveyegge/beads/internal/storage"
itracker "github.com/steveyegge/beads/internal/tracker"
"github.com/steveyegge/beads/internal/types"
)
const defaultBatchPushWorkers = 8
type pushOutcome struct {
created *itracker.BatchPushItem
updated *itracker.BatchPushItem
skipped string
warning string
err *itracker.BatchPushError
trackerIssue *itracker.TrackerIssue
}
type notionAPI interface {
GetCurrentUser(ctx context.Context) (*User, error)
RetrieveDataSource(ctx context.Context, dataSourceID string) (*DataSource, error)
QueryDataSource(ctx context.Context, dataSourceID string) ([]Page, error)
CreatePage(ctx context.Context, dataSourceID string, properties map[string]interface{}) (*Page, error)
UpdatePage(ctx context.Context, pageID string, properties map[string]interface{}) (*Page, error)
ArchivePage(ctx context.Context, pageID string, inTrash bool) (*Page, error)
}
var newNotionClient = func(token string) notionAPI {
return NewClient(token)
}
func init() {
itracker.Register("notion", func() itracker.IssueTracker {
return &Tracker{}
})
}
type Tracker struct {
client notionAPI
store storage.Storage
config *MappingConfig
dataSourceID string
viewURL string
authSource AuthSource
cacheMu sync.RWMutex
issueCache []itracker.TrackerIssue
remoteByPageID map[string]itracker.TrackerIssue
remoteByLocalID map[string]itracker.TrackerIssue
lastQueried int
lastCandidates int
}
func (t *Tracker) Name() string { return "notion" }
func (t *Tracker) DisplayName() string { return "Notion" }
func (t *Tracker) ConfigPrefix() string { return "notion" }
func (t *Tracker) Init(ctx context.Context, store storage.Storage) error {
t.store = store
t.dataSourceID = t.getConfig(ctx, "notion.data_source_id", "NOTION_DATA_SOURCE_ID")
t.viewURL = t.getConfig(ctx, "notion.view_url", "NOTION_VIEW_URL")
auth, err := ResolveAuth(ctx, store)
if err != nil {
return err
}
if auth == nil || strings.TrimSpace(auth.Token) == "" {
return fmt.Errorf("Notion authentication is not configured (set notion.token or export NOTION_TOKEN)")
}
if t.dataSourceID == "" {
return fmt.Errorf("Notion data source not configured (run 'bd notion init --parent <page-id>', 'bd notion connect --url <notion-url>', or set notion.data_source_id)")
}
t.authSource = auth.Source
if t.client == nil {
t.client = newNotionClient(auth.Token)
}
if t.config == nil {
t.config = DefaultMappingConfig()
}
return nil
}
func (t *Tracker) Validate() error {
if t.client == nil {
return fmt.Errorf("Notion tracker not initialized")
}
_, err := t.client.RetrieveDataSource(context.Background(), t.dataSourceID)
if err != nil {
return fmt.Errorf("Notion validation failed: %w", err)
}
return nil
}
func (t *Tracker) Close() error { return nil }
func (t *Tracker) FetchIssues(ctx context.Context, opts itracker.FetchOptions) ([]itracker.TrackerIssue, error) {
if err := t.ensureRemoteIndex(ctx); err != nil {
return nil, err
}
localByExternalIdentifier, localByID, err := t.buildLocalPullIndexes(ctx)
if err != nil {
return nil, err
}
t.cacheMu.RLock()
result := make([]itracker.TrackerIssue, 0, len(t.issueCache))
for _, issue := range t.issueCache {
candidate := cloneTrackerIssue(issue)
if !matchesFetchState(&candidate, opts.State) {
continue
}
if !matchesFetchSince(&candidate, opts.Since) && !shouldBackfillNotionIssue(&candidate, localByExternalIdentifier, localByID) {
continue
}
result = append(result, candidate)
if opts.Limit > 0 && len(result) >= opts.Limit {
break
}
}
queried := len(t.issueCache)
candidates := len(result)
t.cacheMu.RUnlock()
t.cacheMu.Lock()
t.lastQueried = queried
t.lastCandidates = candidates
t.cacheMu.Unlock()
return result, nil
}
func (t *Tracker) LastPullStats() (queried int, candidates int) {
t.cacheMu.RLock()
defer t.cacheMu.RUnlock()
return t.lastQueried, t.lastCandidates
}
func (t *Tracker) buildLocalPullIndexes(ctx context.Context) (map[string]struct{}, map[string]struct{}, error) {
localByExternalIdentifier := map[string]struct{}{}
localByID := map[string]struct{}{}
if t.store == nil {
return localByExternalIdentifier, localByID, nil
}
localIssues, err := t.store.SearchIssues(ctx, "", types.IssueFilter{})
if err != nil {
return nil, nil, fmt.Errorf("searching local issues: %w", err)
}
for _, issue := range localIssues {
if issue == nil {
continue
}
if id := strings.TrimSpace(issue.ID); id != "" {
localByID[id] = struct{}{}
}
if issue.ExternalRef == nil {
continue
}
if identifier := ExtractNotionIdentifier(strings.TrimSpace(*issue.ExternalRef)); identifier != "" {
localByExternalIdentifier[identifier] = struct{}{}
}
}
return localByExternalIdentifier, localByID, nil
}
func (t *Tracker) FetchIssue(ctx context.Context, identifier string) (*itracker.TrackerIssue, error) {
if err := t.ensureRemoteIndex(ctx); err != nil {
return nil, err
}
want := ExtractNotionIdentifier(identifier)
if want == "" {
want = strings.TrimSpace(identifier)
}
t.cacheMu.RLock()
defer t.cacheMu.RUnlock()
if issue, ok := t.remoteByPageID[want]; ok {
cloned := cloneTrackerIssue(issue)
return &cloned, nil
}
if issue, ok := t.remoteByLocalID[want]; ok {
cloned := cloneTrackerIssue(issue)
return &cloned, nil
}
for _, candidate := range t.issueCache {
if candidate.Identifier == want {
cloned := cloneTrackerIssue(candidate)
return &cloned, nil
}
}
return nil, nil
}
func (t *Tracker) CreateIssue(ctx context.Context, issue *types.Issue) (*itracker.TrackerIssue, error) {
pushIssue, err := PushIssueFromIssue(issue, t.config)
if err != nil {
return nil, err
}
page, err := t.client.CreatePage(ctx, t.dataSourceID, BuildPageProperties(pushIssue))
if err != nil {
return nil, err
}
trackerIssue, err := TrackerIssueFromPullIssue(PulledIssueFromPage(*page), t.config)
if err != nil {
return nil, err
}
t.upsertRemoteIssue(trackerIssue)
return trackerIssue, nil
}
func (t *Tracker) UpdateIssue(ctx context.Context, externalID string, issue *types.Issue) (*itracker.TrackerIssue, error) {
pageID := ExtractNotionIdentifier(externalID)
if pageID == "" && issue != nil && issue.ExternalRef != nil {
pageID = ExtractNotionIdentifier(*issue.ExternalRef)
}
if pageID == "" {
return nil, fmt.Errorf("invalid Notion page ID %q", externalID)
}
pushIssue, err := PushIssueFromIssue(issue, t.config)
if err != nil {
return nil, err
}
page, err := t.client.UpdatePage(ctx, pageID, BuildPageProperties(pushIssue))
if err != nil {
return nil, err
}
trackerIssue, err := TrackerIssueFromPullIssue(PulledIssueFromPage(*page), t.config)
if err != nil {
return nil, err
}
t.upsertRemoteIssue(trackerIssue)
return trackerIssue, nil
}
func (t *Tracker) BatchPush(ctx context.Context, issues []*types.Issue, forceIDs map[string]bool) (*itracker.BatchPushResult, error) {
return t.executeBatchPush(ctx, issues, forceIDs, false)
}
func (t *Tracker) BatchPushDryRun(ctx context.Context, issues []*types.Issue, forceIDs map[string]bool) (*itracker.BatchPushResult, error) {
return t.executeBatchPush(ctx, issues, forceIDs, true)
}
func (t *Tracker) executeBatchPush(ctx context.Context, issues []*types.Issue, forceIDs map[string]bool, dryRun bool) (*itracker.BatchPushResult, error) {
if err := t.ensureRemoteIndex(ctx); err != nil {
return nil, err
}
result := &itracker.BatchPushResult{}
if len(issues) == 0 {
return result, nil
}
workerCount := defaultBatchPushWorkers
if len(issues) < workerCount {
workerCount = len(issues)
}
if workerCount < 1 {
workerCount = 1
}
jobs := make(chan *types.Issue)
outcomes := make(chan pushOutcome, len(issues))
var wg sync.WaitGroup
for i := 0; i < workerCount; i++ {
wg.Add(1)
go func() {
defer wg.Done()
for issue := range jobs {
outcomes <- t.pushOne(ctx, issue, forceIDs[issue.ID], dryRun)
}
}()
}
for _, issue := range issues {
if issue == nil {
continue
}
jobs <- issue
}
close(jobs)
wg.Wait()
close(outcomes)
for outcome := range outcomes {
if outcome.created != nil {
result.Created = append(result.Created, *outcome.created)
}
if outcome.updated != nil {
result.Updated = append(result.Updated, *outcome.updated)
}
if strings.TrimSpace(outcome.skipped) != "" {
result.Skipped = append(result.Skipped, outcome.skipped)
}
if strings.TrimSpace(outcome.warning) != "" {
result.Warnings = append(result.Warnings, outcome.warning)
}
if outcome.err != nil {
result.Errors = append(result.Errors, *outcome.err)
}
if outcome.trackerIssue != nil {
t.upsertRemoteIssue(outcome.trackerIssue)
}
}
return result, nil
}
func (t *Tracker) pushOne(ctx context.Context, issue *types.Issue, force, dryRun bool) pushOutcome {
if issue == nil {
return pushOutcome{}
}
pushIssue, err := PushIssueFromIssue(issue, t.config)
if err != nil {
return pushOutcome{err: &itracker.BatchPushError{LocalID: issue.ID, Message: err.Error()}}
}
extRef := derefStr(issue.ExternalRef)
pageID := ExtractNotionIdentifier(extRef)
remote, hasRemote := t.lookupRemoteByPageID(pageID)
if !hasRemote {
remote, hasRemote = t.lookupRemoteByLocalID(issue.ID)
}
if !hasRemote && strings.TrimSpace(extRef) != "" && pageID != "" {
return pushOutcome{
skipped: issue.ID,
warning: fmt.Sprintf("Skipped %s: Notion external_ref points outside the current target; clear external_ref to recreate it in this data source", issue.ID),
}
}
create := !hasRemote
if !create && !force {
if trackerIssueEqual(issue, remote) {
return pushOutcome{skipped: issue.ID}
}
if !remote.UpdatedAt.Before(issue.UpdatedAt) {
return pushOutcome{skipped: issue.ID}
}
}
if create {
if dryRun {
return pushOutcome{
created: &itracker.BatchPushItem{LocalID: issue.ID},
}
}
page, err := t.client.CreatePage(ctx, t.dataSourceID, BuildPageProperties(pushIssue))
if err != nil {
return pushOutcome{err: &itracker.BatchPushError{LocalID: issue.ID, Message: err.Error()}}
}
trackerIssue, err := TrackerIssueFromPullIssue(PulledIssueFromPage(*page), t.config)
if err != nil {
return pushOutcome{err: &itracker.BatchPushError{LocalID: issue.ID, Message: err.Error()}}
}
ref := firstNonEmpty(t.BuildExternalRef(trackerIssue), trackerIssue.URL)
return pushOutcome{
created: &itracker.BatchPushItem{LocalID: issue.ID, ExternalRef: ref},
trackerIssue: trackerIssue,
}
}
if dryRun {
ref := firstNonEmpty(t.BuildExternalRef(remote), remote.URL)
return pushOutcome{
updated: &itracker.BatchPushItem{LocalID: issue.ID, ExternalRef: ref},
}
}
page, err := t.client.UpdatePage(ctx, remote.ID, BuildPageProperties(pushIssue))
if err != nil {
return pushOutcome{err: &itracker.BatchPushError{LocalID: issue.ID, Message: err.Error()}}
}
trackerIssue, err := TrackerIssueFromPullIssue(PulledIssueFromPage(*page), t.config)
if err != nil {
return pushOutcome{err: &itracker.BatchPushError{LocalID: issue.ID, Message: err.Error()}}
}
ref := firstNonEmpty(t.BuildExternalRef(trackerIssue), trackerIssue.URL)
return pushOutcome{
updated: &itracker.BatchPushItem{LocalID: issue.ID, ExternalRef: ref},
trackerIssue: trackerIssue,
}
}
func (t *Tracker) FieldMapper() itracker.FieldMapper {
return NewFieldMapper(t.config)
}
func (t *Tracker) IsExternalRef(ref string) bool {
return IsNotionExternalRef(ref)
}
func (t *Tracker) ExtractIdentifier(ref string) string {
return ExtractNotionIdentifier(ref)
}
func (t *Tracker) BuildExternalRef(issue *itracker.TrackerIssue) string {
if issue == nil {
return ""
}
if canonical, ok := CanonicalizeNotionPageURL(issue.URL); ok {
return canonical
}
if canonical, ok := CanonicalizeNotionPageURL(issue.ID); ok {
return canonical
}
if canonical, ok := CanonicalizeNotionPageURL(issue.Identifier); ok {
return canonical
}
return ""
}
func (t *Tracker) ensureRemoteIndex(ctx context.Context) error {
t.cacheMu.RLock()
ready := t.issueCache != nil && t.remoteByPageID != nil && t.remoteByLocalID != nil
t.cacheMu.RUnlock()
if ready {
return nil
}
pages, err := t.client.QueryDataSource(ctx, t.dataSourceID)
if err != nil {
return err
}
cache := make([]itracker.TrackerIssue, 0, len(pages))
byPageID := make(map[string]itracker.TrackerIssue, len(pages))
byLocalID := make(map[string]itracker.TrackerIssue, len(pages))
for _, page := range pages {
if page.InTrash || page.Archived {
continue
}
pulled := PulledIssueFromPage(page)
trackerIssue, err := TrackerIssueFromPullIssue(pulled, t.config)
if err != nil {
return err
}
cache = append(cache, *trackerIssue)
if id := strings.TrimSpace(trackerIssue.ID); id != "" {
byPageID[id] = *trackerIssue
}
if identifier := strings.TrimSpace(pulled.ID); identifier != "" {
byLocalID[identifier] = *trackerIssue
}
}
t.cacheMu.Lock()
t.issueCache = cache
t.remoteByPageID = byPageID
t.remoteByLocalID = byLocalID
t.cacheMu.Unlock()
return nil
}
func (t *Tracker) lookupRemoteByPageID(pageID string) (*itracker.TrackerIssue, bool) {
return t.lookupRemoteIssue(t.remoteByPageID, pageID)
}
func (t *Tracker) lookupRemoteByLocalID(localID string) (*itracker.TrackerIssue, bool) {
return t.lookupRemoteIssue(t.remoteByLocalID, localID)
}
func (t *Tracker) lookupRemoteIssue(index map[string]itracker.TrackerIssue, identifier string) (*itracker.TrackerIssue, bool) {
identifier = strings.TrimSpace(identifier)
if identifier == "" {
return nil, false
}
t.cacheMu.RLock()
defer t.cacheMu.RUnlock()
issue, ok := index[identifier]
if !ok {
return nil, false
}
cloned := cloneTrackerIssue(issue)
return &cloned, true
}
func (t *Tracker) upsertRemoteIssue(issue *itracker.TrackerIssue) {
if issue == nil {
return
}
cloned := cloneTrackerIssue(*issue)
t.cacheMu.Lock()
defer t.cacheMu.Unlock()
replaced := false
for i := range t.issueCache {
if sameTrackerIssue(t.issueCache[i], *issue) {
t.issueCache[i] = cloned
replaced = true
break
}
}
if !replaced {
t.issueCache = append(t.issueCache, cloned)
}
if t.remoteByPageID == nil {
t.remoteByPageID = make(map[string]itracker.TrackerIssue)
}
if t.remoteByLocalID == nil {
t.remoteByLocalID = make(map[string]itracker.TrackerIssue)
}
if id := strings.TrimSpace(issue.ID); id != "" {
t.remoteByPageID[id] = cloned
}
if identifier := strings.TrimSpace(ExtractNotionIdentifier(issue.URL)); identifier != "" {
t.remoteByPageID[identifier] = cloned
}
if raw, ok := issue.Raw.(*PulledIssue); ok && raw != nil && strings.TrimSpace(raw.ID) != "" {
t.remoteByLocalID[strings.TrimSpace(raw.ID)] = cloned
}
}
func (t *Tracker) getConfig(ctx context.Context, key, envVar string) string {
if t.store != nil {
if value, err := t.store.GetConfig(ctx, key); err == nil && strings.TrimSpace(value) != "" {
return strings.TrimSpace(value)
}
}
if envVar != "" {
return strings.TrimSpace(os.Getenv(envVar))
}
return ""
}
func trackerIssueEqual(local *types.Issue, remote *itracker.TrackerIssue) bool {
if local == nil || remote == nil {
return false
}
if strings.TrimSpace(local.Title) != strings.TrimSpace(remote.Title) {
return false
}
if strings.TrimSpace(local.Description) != strings.TrimSpace(remote.Description) {
return false
}
if local.Priority != remote.Priority {
return false
}
if state, ok := remote.State.(types.Status); !ok || state != local.Status {
return false
}
if issueType, ok := remote.Type.(types.IssueType); !ok || issueType != local.IssueType {
return false
}
if strings.TrimSpace(local.Assignee) != strings.TrimSpace(remote.Assignee) {
return false
}
return equalStringSets(local.Labels, remote.Labels)
}
func equalStringSets(left, right []string) bool {
if len(left) != len(right) {
return false
}
leftCopy := normalizeStringSlice(left)
rightCopy := normalizeStringSlice(right)
for i := range leftCopy {
if leftCopy[i] != rightCopy[i] {
return false
}
}
return true
}
func normalizeStringSlice(values []string) []string {
result := make([]string, 0, len(values))
for _, value := range values {
value = strings.TrimSpace(value)
if value == "" {
continue
}
result = append(result, value)
}
sort.Strings(result)
return result
}
func sameTrackerIssue(left, right itracker.TrackerIssue) bool {
leftIDs := []string{
ExtractNotionIdentifier(left.ID),
ExtractNotionIdentifier(left.Identifier),
ExtractNotionIdentifier(left.URL),
}
rightIDs := []string{
ExtractNotionIdentifier(right.ID),
ExtractNotionIdentifier(right.Identifier),
ExtractNotionIdentifier(right.URL),
}
for _, leftID := range leftIDs {
if leftID == "" {
continue
}
for _, rightID := range rightIDs {
if rightID != "" && leftID == rightID {
return true
}
}
}
return false
}
func cloneTrackerIssue(issue itracker.TrackerIssue) itracker.TrackerIssue {
cloned := issue
if issue.Labels != nil {
cloned.Labels = append([]string(nil), issue.Labels...)
}
return cloned
}
func matchesFetchSince(issue *itracker.TrackerIssue, since *time.Time) bool {
if issue == nil {
return false
}
if since != nil && !issue.UpdatedAt.IsZero() {
// Notion page timestamps are minute-precision. Revisit the boundary minute
// so edits made later in the same minute as last_sync are not lost.
cutoff := since.UTC().Truncate(time.Minute)
if issue.UpdatedAt.Before(cutoff) {
return false
}
}
return true
}
func matchesFetchState(issue *itracker.TrackerIssue, stateFilter string) bool {
if issue == nil {
return false
}
switch strings.TrimSpace(strings.ToLower(stateFilter)) {
case "", "all":
return true
case "open":
status, _ := issue.State.(types.Status)
return status != types.StatusClosed
case "closed":
status, _ := issue.State.(types.Status)
return status == types.StatusClosed
default:
return true
}
}
func shouldBackfillNotionIssue(issue *itracker.TrackerIssue, localByExternalIdentifier, localByID map[string]struct{}) bool {
if issue == nil {
return false
}
for _, ref := range []string{issue.URL, issue.ID, issue.Identifier} {
if identifier := ExtractNotionIdentifier(ref); identifier != "" {
if _, ok := localByExternalIdentifier[identifier]; ok {
return false
}
}
}
raw, ok := issue.Raw.(*PulledIssue)
if !ok || raw == nil {
return false
}
localID := strings.TrimSpace(raw.ID)
if localID == "" {
return false
}
_, ok = localByID[localID]
return !ok
}
func derefStr(value *string) string {
if value == nil {
return ""
}
return strings.TrimSpace(*value)
}

View file

@ -0,0 +1,598 @@
package notion
import (
"context"
"strings"
"testing"
"time"
itracker "github.com/steveyegge/beads/internal/tracker"
"github.com/steveyegge/beads/internal/types"
)
type fakeAPI struct {
user *User
dataSource *DataSource
pages []Page
createdPage *Page
updatedPage *Page
archivePage *Page
queryCalls int
lastCreateDSID string
lastCreateProps map[string]interface{}
lastUpdatePageID string
lastUpdateProps map[string]interface{}
}
func (f *fakeAPI) GetCurrentUser(context.Context) (*User, error) { return f.user, nil }
func (f *fakeAPI) RetrieveDataSource(context.Context, string) (*DataSource, error) {
return f.dataSource, nil
}
func (f *fakeAPI) QueryDataSource(context.Context, string) ([]Page, error) {
f.queryCalls++
return append([]Page(nil), f.pages...), nil
}
func (f *fakeAPI) ArchivePage(context.Context, string, bool) (*Page, error) {
return f.archivePage, nil
}
func (f *fakeAPI) CreatePage(_ context.Context, dataSourceID string, properties map[string]interface{}) (*Page, error) {
f.lastCreateDSID = dataSourceID
f.lastCreateProps = properties
return f.createdPage, nil
}
func (f *fakeAPI) UpdatePage(_ context.Context, pageID string, properties map[string]interface{}) (*Page, error) {
f.lastUpdatePageID = pageID
f.lastUpdateProps = properties
return f.updatedPage, nil
}
func strPtr(value string) *string {
return &value
}
func TestTrackerFetchIssuesFiltersArchivedAndState(t *testing.T) {
t.Parallel()
createdAt := time.Date(2026, 3, 19, 14, 0, 0, 0, time.UTC)
updatedAt := createdAt.Add(5 * time.Minute)
api := &fakeAPI{
pages: []Page{
{
ID: "01234567-89ab-cdef-0123-456789abcdef",
URL: "https://www.notion.so/Task-0123456789abcdef0123456789abcdef",
CreatedTime: createdAt,
LastEditedTime: updatedAt,
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Open task"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-1"}}},
PropertyStatus: {Select: &SelectOption{Name: "Open"}},
PropertyPriority: {Select: &SelectOption{Name: "Medium"}},
PropertyType: {Select: &SelectOption{Name: "Task"}},
},
},
{
ID: "fedcba98-7654-3210-fedc-ba9876543210",
URL: "https://www.notion.so/Closed-fedcba9876543210fedcba9876543210",
CreatedTime: createdAt,
LastEditedTime: updatedAt,
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Closed task"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-2"}}},
PropertyStatus: {Select: &SelectOption{Name: "Closed"}},
PropertyPriority: {Select: &SelectOption{Name: "Low"}},
PropertyType: {Select: &SelectOption{Name: "Task"}},
},
},
{
ID: "11111111-2222-3333-4444-555555555555",
Archived: true,
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Archived"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-3"}}},
PropertyStatus: {Select: &SelectOption{Name: "Open"}},
PropertyPriority: {Select: &SelectOption{Name: "Medium"}},
PropertyType: {Select: &SelectOption{Name: "Task"}},
},
},
},
}
tracker := &Tracker{client: api, config: DefaultMappingConfig(), dataSourceID: "ds_123"}
issues, err := tracker.FetchIssues(context.Background(), itracker.FetchOptions{State: "open"})
if err != nil {
t.Fatalf("FetchIssues returned error: %v", err)
}
if len(issues) != 1 {
t.Fatalf("issues = %d, want 1", len(issues))
}
if issues[0].ID != "01234567-89ab-cdef-0123-456789abcdef" {
t.Fatalf("id = %q", issues[0].ID)
}
}
func TestTrackerFetchIssuesBackfillStillHonorsClosedState(t *testing.T) {
t.Parallel()
api := &fakeAPI{
pages: []Page{
{
ID: "01234567-89ab-cdef-0123-456789abcdef",
URL: "https://www.notion.so/Open-0123456789abcdef0123456789abcdef",
CreatedTime: time.Now().UTC().Add(-2 * time.Hour),
LastEditedTime: time.Now().UTC().Add(-2 * time.Hour),
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Open"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-open"}}},
PropertyStatus: {Select: &SelectOption{Name: "Open"}},
PropertyPriority: {Select: &SelectOption{Name: "Medium"}},
PropertyType: {Select: &SelectOption{Name: "Task"}},
},
},
{
ID: "fedcba98-7654-3210-fedc-ba9876543210",
URL: "https://www.notion.so/Closed-fedcba9876543210fedcba9876543210",
CreatedTime: time.Now().UTC().Add(-2 * time.Hour),
LastEditedTime: time.Now().UTC().Add(-2 * time.Hour),
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Closed"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-closed"}}},
PropertyStatus: {Select: &SelectOption{Name: "Closed"}},
PropertyPriority: {Select: &SelectOption{Name: "Medium"}},
PropertyType: {Select: &SelectOption{Name: "Task"}},
},
},
},
}
tracker := &Tracker{client: api, config: DefaultMappingConfig(), dataSourceID: "ds_123"}
since := time.Now().UTC().Add(-30 * time.Minute)
issues, err := tracker.FetchIssues(context.Background(), itracker.FetchOptions{
State: "closed",
Since: &since,
})
if err != nil {
t.Fatalf("FetchIssues returned error: %v", err)
}
if len(issues) != 1 {
t.Fatalf("issues = %d, want 1", len(issues))
}
if issues[0].Title != "Closed" {
t.Fatalf("title = %q, want Closed", issues[0].Title)
}
}
func TestTrackerFetchIssuesExcludesEqualLastSyncBoundary(t *testing.T) {
t.Parallel()
boundary := time.Date(2026, 3, 22, 9, 54, 51, 0, time.UTC)
api := &fakeAPI{
pages: []Page{
{
ID: "01234567-89ab-cdef-0123-456789abcdef",
URL: "https://www.notion.so/Task-0123456789abcdef0123456789abcdef",
CreatedTime: boundary.Add(-10 * time.Minute),
LastEditedTime: boundary,
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Equal boundary"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-1"}}},
PropertyStatus: {Select: &SelectOption{Name: "Open"}},
PropertyPriority: {Select: &SelectOption{Name: "Medium"}},
PropertyType: {Select: &SelectOption{Name: "Task"}},
},
},
{
ID: "11111111-2222-3333-4444-555555555555",
URL: "https://www.notion.so/Task-11111111222233334444555555555555",
CreatedTime: boundary.Add(-5 * time.Minute),
LastEditedTime: boundary.Add(time.Second),
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "After boundary"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-2"}}},
PropertyStatus: {Select: &SelectOption{Name: "Open"}},
PropertyPriority: {Select: &SelectOption{Name: "Medium"}},
PropertyType: {Select: &SelectOption{Name: "Task"}},
},
},
},
}
tracker := &Tracker{client: api, config: DefaultMappingConfig(), dataSourceID: "ds_123"}
boundary = boundary.Add(23 * time.Second)
issues, err := tracker.FetchIssues(context.Background(), itracker.FetchOptions{Since: &boundary})
if err != nil {
t.Fatalf("FetchIssues returned error: %v", err)
}
if len(issues) != 2 {
t.Fatalf("issues = %d, want 2", len(issues))
}
if issues[0].Title != "Equal boundary" || issues[1].Title != "After boundary" {
t.Fatalf("titles = %q, %q", issues[0].Title, issues[1].Title)
}
queried, candidates := tracker.LastPullStats()
if queried != 2 || candidates != 2 {
t.Fatalf("LastPullStats = (%d, %d), want (2, 2)", queried, candidates)
}
}
func TestTrackerCreateAndUpdateIssue(t *testing.T) {
t.Parallel()
createdPage := &Page{
ID: "01234567-89ab-cdef-0123-456789abcdef",
URL: "https://www.notion.so/Task-0123456789abcdef0123456789abcdef",
CreatedTime: time.Date(2026, 3, 19, 14, 0, 0, 0, time.UTC),
LastEditedTime: time.Date(2026, 3, 19, 14, 5, 0, 0, time.UTC),
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Create me"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-1"}}},
PropertyStatus: {Select: &SelectOption{Name: "Open"}},
PropertyPriority: {Select: &SelectOption{Name: "Medium"}},
PropertyType: {Select: &SelectOption{Name: "Task"}},
},
}
updatedPage := &Page{
ID: "01234567-89ab-cdef-0123-456789abcdef",
URL: "https://www.notion.so/Task-0123456789abcdef0123456789abcdef",
CreatedTime: createdPage.CreatedTime,
LastEditedTime: createdPage.LastEditedTime.Add(10 * time.Minute),
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Update me"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-1"}}},
PropertyStatus: {Select: &SelectOption{Name: "In Progress"}},
PropertyPriority: {Select: &SelectOption{Name: "High"}},
PropertyType: {Select: &SelectOption{Name: "Feature"}},
},
}
api := &fakeAPI{
createdPage: createdPage,
updatedPage: updatedPage,
}
tracker := &Tracker{client: api, config: DefaultMappingConfig(), dataSourceID: "ds_123"}
created, err := tracker.CreateIssue(context.Background(), &types.Issue{
ID: "bd-1",
Title: "Create me",
Status: types.StatusOpen,
Priority: 2,
IssueType: types.TypeTask,
})
if err != nil {
t.Fatalf("CreateIssue returned error: %v", err)
}
if api.lastCreateDSID != "ds_123" {
t.Fatalf("data source id = %q", api.lastCreateDSID)
}
if created.URL != "https://www.notion.so/0123456789abcdef0123456789abcdef" {
t.Fatalf("created URL = %q", created.URL)
}
updated, err := tracker.UpdateIssue(context.Background(), "https://www.notion.so/Task-0123456789abcdef0123456789abcdef", &types.Issue{
ID: "bd-1",
Title: "Update me",
Status: types.StatusInProgress,
Priority: 1,
IssueType: types.TypeFeature,
})
if err != nil {
t.Fatalf("UpdateIssue returned error: %v", err)
}
if api.lastUpdatePageID != "01234567-89ab-cdef-0123-456789abcdef" {
t.Fatalf("update page id = %q", api.lastUpdatePageID)
}
if updated.Title != "Update me" {
t.Fatalf("updated title = %q", updated.Title)
}
}
func TestTrackerBuildExternalRefFallbacks(t *testing.T) {
t.Parallel()
tracker := &Tracker{}
if got := tracker.BuildExternalRef(&itracker.TrackerIssue{ID: "01234567-89ab-cdef-0123-456789abcdef"}); got != "https://www.notion.so/0123456789abcdef0123456789abcdef" {
t.Fatalf("got = %q", got)
}
}
func TestTrackerBatchPushReusesRemoteInventory(t *testing.T) {
t.Parallel()
createdAt := time.Date(2026, 3, 19, 14, 0, 0, 0, time.UTC)
remotePage := Page{
ID: "01234567-89ab-cdef-0123-456789abcdef",
URL: "https://www.notion.so/Task-0123456789abcdef0123456789abcdef",
CreatedTime: createdAt,
LastEditedTime: createdAt.Add(5 * time.Minute),
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Existing remote"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-1"}}},
PropertyStatus: {Select: &SelectOption{Name: "Open"}},
PropertyPriority: {Select: &SelectOption{Name: "Medium"}},
PropertyType: {Select: &SelectOption{Name: "Task"}},
},
}
api := &fakeAPI{
pages: []Page{remotePage},
createdPage: &Page{
ID: "11111111-2222-3333-4444-555555555555",
URL: "https://www.notion.so/New-11111111222233334444555555555555",
CreatedTime: createdAt,
LastEditedTime: createdAt.Add(10 * time.Minute),
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Create me"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-2"}}},
PropertyStatus: {Select: &SelectOption{Name: "Open"}},
PropertyPriority: {Select: &SelectOption{Name: "Medium"}},
PropertyType: {Select: &SelectOption{Name: "Task"}},
},
},
updatedPage: &Page{
ID: remotePage.ID,
URL: remotePage.URL,
CreatedTime: remotePage.CreatedTime,
LastEditedTime: remotePage.LastEditedTime.Add(10 * time.Minute),
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Updated local"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-1"}}},
PropertyStatus: {Select: &SelectOption{Name: "In Progress"}},
PropertyPriority: {Select: &SelectOption{Name: "High"}},
PropertyType: {Select: &SelectOption{Name: "Feature"}},
},
},
}
tracker := &Tracker{client: api, config: DefaultMappingConfig(), dataSourceID: "ds_123"}
result, err := tracker.BatchPush(context.Background(), []*types.Issue{
{
ID: "bd-1",
Title: "Updated local",
Status: types.StatusInProgress,
Priority: 1,
IssueType: types.TypeFeature,
ExternalRef: strPtr("https://www.notion.so/Task-0123456789abcdef0123456789abcdef"),
UpdatedAt: remotePage.LastEditedTime.Add(30 * time.Minute),
},
{
ID: "bd-2",
Title: "Create me",
Status: types.StatusOpen,
Priority: 2,
IssueType: types.TypeTask,
UpdatedAt: remotePage.LastEditedTime.Add(30 * time.Minute),
},
}, map[string]bool{})
if err != nil {
t.Fatalf("BatchPush returned error: %v", err)
}
if api.queryCalls != 1 {
t.Fatalf("queryCalls = %d, want 1", api.queryCalls)
}
if len(result.Updated) != 1 || len(result.Created) != 1 {
t.Fatalf("result = %+v", result)
}
if api.lastUpdatePageID != "01234567-89ab-cdef-0123-456789abcdef" {
t.Fatalf("lastUpdatePageID = %q", api.lastUpdatePageID)
}
if api.lastCreateDSID != "ds_123" {
t.Fatalf("lastCreateDSID = %q", api.lastCreateDSID)
}
}
func TestTrackerBatchPushMatchesCurrentTargetByLocalID(t *testing.T) {
t.Parallel()
createdAt := time.Date(2026, 3, 19, 14, 0, 0, 0, time.UTC)
remotePage := Page{
ID: "01234567-89ab-cdef-0123-456789abcdef",
URL: "https://www.notion.so/Task-0123456789abcdef0123456789abcdef",
CreatedTime: createdAt,
LastEditedTime: createdAt.Add(5 * time.Minute),
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Existing remote"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-1"}}},
PropertyStatus: {Select: &SelectOption{Name: "Open"}},
PropertyPriority: {Select: &SelectOption{Name: "Medium"}},
PropertyType: {Select: &SelectOption{Name: "Task"}},
},
}
api := &fakeAPI{
pages: []Page{remotePage},
updatedPage: &Page{
ID: remotePage.ID,
URL: remotePage.URL,
CreatedTime: remotePage.CreatedTime,
LastEditedTime: remotePage.LastEditedTime.Add(10 * time.Minute),
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Updated local"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-1"}}},
PropertyStatus: {Select: &SelectOption{Name: "In Progress"}},
PropertyPriority: {Select: &SelectOption{Name: "High"}},
PropertyType: {Select: &SelectOption{Name: "Feature"}},
},
},
}
tracker := &Tracker{client: api, config: DefaultMappingConfig(), dataSourceID: "ds_123"}
foreignRef := "https://www.notion.so/foreign-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
result, err := tracker.BatchPush(context.Background(), []*types.Issue{
{
ID: "bd-1",
Title: "Updated local",
Status: types.StatusInProgress,
Priority: 1,
IssueType: types.TypeFeature,
ExternalRef: &foreignRef,
UpdatedAt: remotePage.LastEditedTime.Add(30 * time.Minute),
},
}, map[string]bool{})
if err != nil {
t.Fatalf("BatchPush returned error: %v", err)
}
if len(result.Updated) != 1 || len(result.Created) != 0 {
t.Fatalf("result = %+v", result)
}
if api.lastUpdatePageID != remotePage.ID {
t.Fatalf("lastUpdatePageID = %q, want %q", api.lastUpdatePageID, remotePage.ID)
}
if api.lastCreateDSID != "" {
t.Fatalf("lastCreateDSID = %q, want empty", api.lastCreateDSID)
}
}
func TestTrackerBatchPushSkipsStaleExternalRefOutsideCurrentTarget(t *testing.T) {
t.Parallel()
api := &fakeAPI{}
tracker := &Tracker{client: api, config: DefaultMappingConfig(), dataSourceID: "ds_123"}
foreignRef := "https://www.notion.so/foreign-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
result, err := tracker.BatchPush(context.Background(), []*types.Issue{
{
ID: "bd-1",
Title: "Stale ref",
Status: types.StatusOpen,
Priority: 2,
IssueType: types.TypeTask,
ExternalRef: &foreignRef,
UpdatedAt: time.Now().UTC(),
},
}, map[string]bool{})
if err != nil {
t.Fatalf("BatchPush returned error: %v", err)
}
if len(result.Skipped) != 1 || result.Skipped[0] != "bd-1" {
t.Fatalf("skipped = %+v", result.Skipped)
}
if len(result.Warnings) != 1 || !strings.Contains(result.Warnings[0], "outside the current target") {
t.Fatalf("warnings = %+v", result.Warnings)
}
if api.lastCreateDSID != "" || api.lastUpdatePageID != "" {
t.Fatalf("unexpected mutation create=%q update=%q", api.lastCreateDSID, api.lastUpdatePageID)
}
}
func TestTrackerBatchPushDryRunSkipsStaleExternalRefOutsideCurrentTarget(t *testing.T) {
t.Parallel()
api := &fakeAPI{}
tracker := &Tracker{client: api, config: DefaultMappingConfig(), dataSourceID: "ds_123"}
foreignRef := "https://www.notion.so/foreign-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
result, err := tracker.BatchPushDryRun(context.Background(), []*types.Issue{
{
ID: "bd-1",
Title: "Stale ref",
Status: types.StatusOpen,
Priority: 2,
IssueType: types.TypeTask,
ExternalRef: &foreignRef,
UpdatedAt: time.Now().UTC(),
},
}, map[string]bool{})
if err != nil {
t.Fatalf("BatchPushDryRun returned error: %v", err)
}
if len(result.Skipped) != 1 || result.Skipped[0] != "bd-1" {
t.Fatalf("skipped = %+v", result.Skipped)
}
if len(result.Updated) != 0 || len(result.Created) != 0 {
t.Fatalf("result = %+v", result)
}
if len(result.Warnings) != 1 || !strings.Contains(result.Warnings[0], "outside the current target") {
t.Fatalf("warnings = %+v", result.Warnings)
}
if api.lastCreateDSID != "" || api.lastUpdatePageID != "" {
t.Fatalf("unexpected mutation create=%q update=%q", api.lastCreateDSID, api.lastUpdatePageID)
}
}
func TestTrackerBatchPushDryRunTreatsLabelOnlyChangeAsUpdate(t *testing.T) {
t.Parallel()
createdAt := time.Date(2026, 3, 19, 14, 0, 0, 0, time.UTC)
remotePage := Page{
ID: "01234567-89ab-cdef-0123-456789abcdef",
URL: "https://www.notion.so/Task-0123456789abcdef0123456789abcdef",
CreatedTime: createdAt,
LastEditedTime: createdAt.Add(5 * time.Minute),
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Existing remote"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-1"}}},
PropertyStatus: {Select: &SelectOption{Name: "Open"}},
PropertyPriority: {Select: &SelectOption{Name: "Medium"}},
PropertyType: {Select: &SelectOption{Name: "Task"}},
PropertyLabels: {MultiSelect: []SelectOption{{Name: "matrix-a"}, {Name: "matrix-b"}}},
},
}
api := &fakeAPI{pages: []Page{remotePage}}
tracker := &Tracker{client: api, config: DefaultMappingConfig(), dataSourceID: "ds_123"}
result, err := tracker.BatchPushDryRun(context.Background(), []*types.Issue{
{
ID: "bd-1",
Title: "Existing remote",
Status: types.StatusOpen,
Priority: 2,
IssueType: types.TypeTask,
Labels: []string{"matrix-a", "matrix-c"},
UpdatedAt: remotePage.LastEditedTime.Add(30 * time.Minute),
},
}, map[string]bool{})
if err != nil {
t.Fatalf("BatchPushDryRun returned error: %v", err)
}
if len(result.Updated) != 1 || result.Updated[0].LocalID != "bd-1" {
t.Fatalf("updated = %+v", result.Updated)
}
if len(result.Skipped) != 0 {
t.Fatalf("skipped = %+v", result.Skipped)
}
if api.lastCreateDSID != "" || api.lastUpdatePageID != "" {
t.Fatalf("unexpected mutation create=%q update=%q", api.lastCreateDSID, api.lastUpdatePageID)
}
}
func TestTrackerBatchPushDryRunSkipsLabelOrderOnlyDifference(t *testing.T) {
t.Parallel()
createdAt := time.Date(2026, 3, 19, 14, 0, 0, 0, time.UTC)
remotePage := Page{
ID: "01234567-89ab-cdef-0123-456789abcdef",
URL: "https://www.notion.so/Task-0123456789abcdef0123456789abcdef",
CreatedTime: createdAt,
LastEditedTime: createdAt.Add(5 * time.Minute),
Properties: map[string]PageProperty{
PropertyTitle: {Title: []RichText{{PlainText: "Existing remote"}}},
PropertyBeadsID: {RichText: []RichText{{PlainText: "bd-1"}}},
PropertyStatus: {Select: &SelectOption{Name: "Open"}},
PropertyPriority: {Select: &SelectOption{Name: "Medium"}},
PropertyType: {Select: &SelectOption{Name: "Task"}},
PropertyLabels: {MultiSelect: []SelectOption{{Name: "matrix-b"}, {Name: "matrix-a"}}},
},
}
api := &fakeAPI{pages: []Page{remotePage}}
tracker := &Tracker{client: api, config: DefaultMappingConfig(), dataSourceID: "ds_123"}
result, err := tracker.BatchPushDryRun(context.Background(), []*types.Issue{
{
ID: "bd-1",
Title: "Existing remote",
Status: types.StatusOpen,
Priority: 2,
IssueType: types.TypeTask,
Labels: []string{"matrix-a", "matrix-b"},
UpdatedAt: remotePage.LastEditedTime.Add(30 * time.Minute),
},
}, map[string]bool{})
if err != nil {
t.Fatalf("BatchPushDryRun returned error: %v", err)
}
if len(result.Skipped) != 1 || result.Skipped[0] != "bd-1" {
t.Fatalf("skipped = %+v", result.Skipped)
}
if len(result.Updated) != 0 || len(result.Created) != 0 {
t.Fatalf("result = %+v", result)
}
if api.lastCreateDSID != "" || api.lastUpdatePageID != "" {
t.Fatalf("unexpected mutation create=%q update=%q", api.lastCreateDSID, api.lastUpdatePageID)
}
}

296
internal/notion/types.go Normal file
View file

@ -0,0 +1,296 @@
package notion
import (
"encoding/json"
"strings"
"time"
)
const (
DefaultDatabaseTitle = "Beads Issues"
PropertyTitle = "Name"
PropertyBeadsID = "Beads ID"
PropertyStatus = "Status"
PropertyPriority = "Priority"
PropertyType = "Type"
PropertyDescription = "Description"
PropertyAssignee = "Assignee"
PropertyLabels = "Labels"
)
var requiredSchemaProperties = map[string]string{
PropertyTitle: "title",
PropertyBeadsID: "rich_text",
PropertyStatus: "select",
PropertyPriority: "select",
PropertyType: "select",
PropertyDescription: "rich_text",
PropertyAssignee: "rich_text",
PropertyLabels: "multi_select",
}
// StatusResponse is the machine-readable output from `bd notion status --json`.
type StatusResponse struct {
Ready bool `json:"ready"`
DataSourceID string `json:"data_source_id,omitempty"`
ViewURL string `json:"view_url,omitempty"`
SchemaVersion string `json:"schema_version,omitempty"`
Configured bool `json:"configured,omitempty"`
SavedConfig bool `json:"saved_config_present,omitempty"`
ConfigSource string `json:"config_source,omitempty"`
Auth *StatusAuth `json:"auth,omitempty"`
Database *StatusDatabase `json:"database,omitempty"`
Views []StatusView `json:"views,omitempty"`
Schema *StatusSchema `json:"schema,omitempty"`
Archive *ArchiveCapability `json:"archive,omitempty"`
State *StatusState `json:"state,omitempty"`
Error string `json:"error,omitempty"`
}
// StatusAuth describes authentication state.
type StatusAuth struct {
OK bool `json:"ok"`
Source string `json:"source,omitempty"`
User *StatusUser `json:"user,omitempty"`
}
// StatusUser describes the authenticated Notion user.
type StatusUser struct {
ID string `json:"id,omitempty"`
Name string `json:"name,omitempty"`
Email string `json:"email,omitempty"`
Type string `json:"type,omitempty"`
}
// StatusDatabase describes the selected Notion database.
type StatusDatabase struct {
ID string `json:"id,omitempty"`
Title string `json:"title,omitempty"`
URL string `json:"url,omitempty"`
}
// StatusView describes a database view.
type StatusView struct {
ID string `json:"id,omitempty"`
Name *string `json:"name,omitempty"`
URL string `json:"url,omitempty"`
Type *string `json:"type,omitempty"`
}
// StatusSchema describes schema validation state.
type StatusSchema struct {
Checked bool `json:"checked,omitempty"`
Required []string `json:"required,omitempty"`
Optional []string `json:"optional,omitempty"`
Detected []string `json:"detected,omitempty"`
Missing []string `json:"missing,omitempty"`
OptionalMissing []string `json:"optional_missing,omitempty"`
}
// ArchiveCapability describes archive support visibility.
type ArchiveCapability struct {
Supported bool `json:"supported"`
Mode string `json:"mode,omitempty"`
Reason string `json:"reason,omitempty"`
SupportedCommands []string `json:"supported_commands,omitempty"`
}
// StatusState captures local bridge state information.
type StatusState struct {
Path string `json:"path,omitempty"`
Present bool `json:"present,omitempty"`
ManagedCount int `json:"managed_count,omitempty"`
ViewConfigured bool `json:"view_configured,omitempty"`
DoctorSummary *DoctorSummary `json:"doctor_summary,omitempty"`
}
// DoctorSummary captures machine-readable state health.
type DoctorSummary struct {
OK bool `json:"ok"`
TotalCount int `json:"total_count,omitempty"`
OKCount int `json:"ok_count,omitempty"`
MissingPageCount int `json:"missing_page_count,omitempty"`
IDDriftCount int `json:"id_drift_count,omitempty"`
PropertyMismatchCount int `json:"property_mismatch_count,omitempty"`
}
// PulledIssue is the normalized issue record returned by integrated Notion pull.
type PulledIssue struct {
ID string `json:"id,omitempty"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
Status string `json:"status,omitempty"`
Priority string `json:"priority,omitempty"`
Type string `json:"type,omitempty"`
IssueType string `json:"issue_type,omitempty"`
Assignee string `json:"assignee,omitempty"`
Labels []string `json:"labels,omitempty"`
ExternalRef string `json:"external_ref,omitempty"`
NotionPageID string `json:"notion_page_id,omitempty"`
CreatedAt NullableString `json:"created_at,omitempty"`
UpdatedAt NullableString `json:"updated_at,omitempty"`
}
// NullableString accepts either a JSON string or null and normalizes null to the zero value.
type NullableString string
// UnmarshalJSON decodes a string or null into the nullable string.
func (s *NullableString) UnmarshalJSON(data []byte) error {
if string(data) == "null" {
*s = ""
return nil
}
var value string
if err := json.Unmarshal(data, &value); err != nil {
return err
}
*s = NullableString(value)
return nil
}
type PushIssue struct {
ID string `json:"id,omitempty"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
Status string `json:"status,omitempty"`
Priority string `json:"priority,omitempty"`
IssueType string `json:"issue_type,omitempty"`
Assignee string `json:"assignee,omitempty"`
Labels []string `json:"labels,omitempty"`
ExternalRef string `json:"external_ref,omitempty"`
}
type Person struct {
Email string `json:"email,omitempty"`
}
type User struct {
Object string `json:"object,omitempty"`
ID string `json:"id,omitempty"`
Name string `json:"name,omitempty"`
Type string `json:"type,omitempty"`
Person *Person `json:"person,omitempty"`
}
type DataSource struct {
Object string `json:"object,omitempty"`
ID string `json:"id,omitempty"`
URL string `json:"url,omitempty"`
Title []RichText `json:"title,omitempty"`
Properties map[string]DataSourceProperty `json:"properties,omitempty"`
}
type Database struct {
Object string `json:"object,omitempty"`
ID string `json:"id,omitempty"`
URL string `json:"url,omitempty"`
Title []RichText `json:"title,omitempty"`
DataSources []DataSourceReference `json:"data_sources,omitempty"`
Properties map[string]any `json:"properties,omitempty"`
}
type DataSourceReference struct {
ID string `json:"id,omitempty"`
Name string `json:"name,omitempty"`
}
type DataSourceProperty struct {
ID string `json:"id,omitempty"`
Type string `json:"type,omitempty"`
}
type QueryDataSourceResponse struct {
Results []Page `json:"results,omitempty"`
HasMore bool `json:"has_more,omitempty"`
NextCursor string `json:"next_cursor,omitempty"`
}
type Page struct {
Object string `json:"object,omitempty"`
ID string `json:"id,omitempty"`
URL string `json:"url,omitempty"`
InTrash bool `json:"in_trash,omitempty"`
Archived bool `json:"archived,omitempty"`
CreatedTime time.Time `json:"created_time,omitempty"`
LastEditedTime time.Time `json:"last_edited_time,omitempty"`
Properties map[string]PageProperty `json:"properties,omitempty"`
}
type PageProperty struct {
ID string `json:"id,omitempty"`
Type string `json:"type,omitempty"`
Title []RichText `json:"title,omitempty"`
RichText []RichText `json:"rich_text,omitempty"`
Select *SelectOption `json:"select,omitempty"`
MultiSelect []SelectOption `json:"multi_select,omitempty"`
}
type RichText struct {
Type string `json:"type,omitempty"`
PlainText string `json:"plain_text,omitempty"`
Text *TextObject `json:"text,omitempty"`
}
type TextObject struct {
Content string `json:"content,omitempty"`
}
type SelectOption struct {
Name string `json:"name,omitempty"`
}
func DataSourceTitle(items []RichText) string {
parts := make([]string, 0, len(items))
for _, item := range items {
switch {
case item.PlainText != "":
parts = append(parts, item.PlainText)
case item.Text != nil && item.Text.Content != "":
parts = append(parts, item.Text.Content)
}
}
return strings.Join(parts, "")
}
func richTextRequest(content string) []map[string]interface{} {
content = strings.TrimSpace(content)
if content == "" {
return []map[string]interface{}{}
}
return []map[string]interface{}{
{
"type": "text",
"text": map[string]interface{}{
"content": content,
},
},
}
}
func BuildInitialDataSourceProperties() map[string]interface{} {
return map[string]interface{}{
PropertyTitle: map[string]interface{}{"title": map[string]interface{}{}},
PropertyBeadsID: map[string]interface{}{"rich_text": map[string]interface{}{}},
PropertyStatus: map[string]interface{}{"select": map[string]interface{}{"options": selectOptions("Open", "In Progress", "Blocked", "Deferred", "Closed")}},
PropertyPriority: map[string]interface{}{"select": map[string]interface{}{"options": selectOptions("Critical", "High", "Medium", "Low", "Backlog")}},
PropertyType: map[string]interface{}{"select": map[string]interface{}{"options": selectOptions("Bug", "Feature", "Task", "Epic", "Chore")}},
PropertyDescription: map[string]interface{}{"rich_text": map[string]interface{}{}},
PropertyAssignee: map[string]interface{}{"rich_text": map[string]interface{}{}},
PropertyLabels: map[string]interface{}{"multi_select": map[string]interface{}{}},
}
}
func selectOptions(names ...string) []map[string]interface{} {
options := make([]map[string]interface{}, 0, len(names))
for _, name := range names {
name = strings.TrimSpace(name)
if name == "" {
continue
}
options = append(options, map[string]interface{}{"name": name})
}
return options
}

View file

@ -4,6 +4,8 @@ import (
"context"
"encoding/json"
"fmt"
"sort"
"strings"
"time"
"go.opentelemetry.io/otel"
@ -105,7 +107,6 @@ func (e *Engine) Sync(ctx context.Context, opts SyncOptions) (*SyncResult, error
defer span.End()
result := &SyncResult{Success: true}
now := time.Now().UTC()
// Default to bidirectional if neither specified
if !opts.Pull && !opts.Push {
@ -117,9 +118,22 @@ func (e *Engine) Sync(ctx context.Context, opts SyncOptions) (*SyncResult, error
skipPushIDs := make(map[string]bool)
forcePushIDs := make(map[string]bool)
// Phase 1: Pull
allowPullOverwriteIDs := make(map[string]bool)
// Phase 1: Detect conflicts (only for bidirectional sync)
if opts.Pull && opts.Push {
conflicts, err := e.DetectConflicts(ctx)
if err != nil {
e.warn("Failed to detect conflicts: %v", err)
} else if len(conflicts) > 0 {
result.Stats.Conflicts = len(conflicts)
e.resolveConflicts(opts, conflicts, skipPushIDs, forcePushIDs, allowPullOverwriteIDs)
}
}
// Phase 2: Pull
if opts.Pull {
pullStats, err := e.doPull(ctx, opts)
pullStats, err := e.doPull(ctx, opts, allowPullOverwriteIDs)
if err != nil {
result.Success = false
result.Error = fmt.Sprintf("pull failed: %v", err)
@ -127,23 +141,13 @@ func (e *Engine) Sync(ctx context.Context, opts SyncOptions) (*SyncResult, error
span.SetStatus(codes.Error, result.Error)
return result, err
}
result.PullStats = *pullStats
result.Stats.Pulled = pullStats.Created + pullStats.Updated
result.Stats.Created += pullStats.Created
result.Stats.Updated += pullStats.Updated
result.Stats.Skipped += pullStats.Skipped
}
// Phase 2: Detect conflicts (only for bidirectional sync)
if opts.Pull && opts.Push {
conflicts, err := e.DetectConflicts(ctx)
if err != nil {
e.warn("Failed to detect conflicts: %v", err)
} else if len(conflicts) > 0 {
result.Stats.Conflicts = len(conflicts)
e.resolveConflicts(ctx, opts, conflicts, skipPushIDs, forcePushIDs)
}
}
// Phase 3: Push
if opts.Push {
pushStats, err := e.doPush(ctx, opts, skipPushIDs, forcePushIDs)
@ -154,11 +158,13 @@ func (e *Engine) Sync(ctx context.Context, opts SyncOptions) (*SyncResult, error
span.SetStatus(codes.Error, result.Error)
return result, err
}
result.PushStats = *pushStats
result.Stats.Pushed = pushStats.Created + pushStats.Updated
result.Stats.Created += pushStats.Created
result.Stats.Updated += pushStats.Updated
result.Stats.Skipped += pushStats.Skipped
result.Stats.Errors += pushStats.Errors
result.Warnings = append(result.Warnings, pushStats.Warnings...)
}
// Record final stats as span attributes.
@ -174,7 +180,7 @@ func (e *Engine) Sync(ctx context.Context, opts SyncOptions) (*SyncResult, error
// Update last_sync timestamp
if !opts.DryRun {
lastSync := now.Format(time.RFC3339)
lastSync := time.Now().UTC().Format(time.RFC3339Nano)
key := e.Tracker.ConfigPrefix() + ".last_sync"
if err := e.Store.SetConfig(ctx, key, lastSync); err != nil {
e.warn("Failed to update last_sync: %v", err)
@ -200,7 +206,7 @@ func (e *Engine) DetectConflicts(ctx context.Context) ([]Conflict, error) {
return nil, nil // No previous sync, no conflicts possible
}
lastSync, err := time.Parse(time.RFC3339, lastSyncStr)
lastSync, err := parseSyncTime(lastSyncStr)
if err != nil {
return nil, fmt.Errorf("invalid last_sync timestamp %q: %w", lastSyncStr, err)
}
@ -252,7 +258,7 @@ func (e *Engine) DetectConflicts(ctx context.Context) ([]Conflict, error) {
}
// doPull imports issues from the external tracker into beads.
func (e *Engine) doPull(ctx context.Context, opts SyncOptions) (*PullStats, error) {
func (e *Engine) doPull(ctx context.Context, opts SyncOptions, allowOverwriteIDs map[string]bool) (*PullStats, error) {
ctx, span := syncTracer.Start(ctx, "tracker.pull",
trace.WithAttributes(
attribute.String("sync.tracker", e.Tracker.DisplayName()),
@ -268,7 +274,7 @@ func (e *Engine) doPull(ctx context.Context, opts SyncOptions) (*PullStats, erro
var lastSync *time.Time
key := e.Tracker.ConfigPrefix() + ".last_sync"
if lastSyncStr, err := e.Store.GetConfig(ctx, key); err == nil && lastSyncStr != "" {
if t, err := time.Parse(time.RFC3339, lastSyncStr); err == nil {
if t, err := parseSyncTime(lastSyncStr); err == nil {
fetchOpts.Since = &t
lastSync = &t
stats.Incremental = true
@ -276,13 +282,42 @@ func (e *Engine) doPull(ctx context.Context, opts SyncOptions) (*PullStats, erro
}
}
localIssues, err := e.Store.SearchIssues(ctx, "", types.IssueFilter{})
if err != nil {
return nil, fmt.Errorf("searching local issues: %w", err)
}
localByExternalIdentifier := make(map[string]*types.Issue, len(localIssues))
localByID := make(map[string]*types.Issue, len(localIssues))
for _, localIssue := range localIssues {
if localIssue == nil {
continue
}
if localID := strings.TrimSpace(localIssue.ID); localID != "" {
localByID[localID] = localIssue
}
if localIssue == nil || localIssue.ExternalRef == nil {
continue
}
localRef := strings.TrimSpace(*localIssue.ExternalRef)
if localRef == "" || !e.Tracker.IsExternalRef(localRef) {
continue
}
identifier := e.Tracker.ExtractIdentifier(localRef)
if identifier == "" {
continue
}
localByExternalIdentifier[identifier] = localIssue
}
// Fetch issues from external tracker
extIssues, err := e.Tracker.FetchIssues(ctx, fetchOpts)
if err != nil {
return nil, fmt.Errorf("fetching issues: %w", err)
}
e.msg("Fetched %d issues from %s", len(extIssues), e.Tracker.DisplayName())
stats.Candidates = len(extIssues)
if provider, ok := e.Tracker.(PullStatsProvider); ok {
stats.Queried, stats.Candidates = provider.LastPullStats()
}
mapper := e.Tracker.FieldMapper()
var pendingDeps []DependencyInfo
@ -296,21 +331,26 @@ func (e *Engine) doPull(ctx context.Context, opts SyncOptions) (*PullStats, erro
}
}
if opts.DryRun {
e.msg("[dry-run] Would import: %s - %s", extIssue.Identifier, extIssue.Title)
stats.Created++
continue
}
// Check if we already have this issue
// Check if we already have this issue before dry-run so preview stats
// distinguish creates from updates.
ref := e.Tracker.BuildExternalRef(&extIssue)
existing, _ := e.Store.GetIssueByExternalRef(ctx, ref)
if existing == nil && ref != "" {
identifier := e.Tracker.ExtractIdentifier(ref)
if identifier != "" {
existing = localByExternalIdentifier[identifier]
}
}
conv := mapper.IssueToBeads(&extIssue)
if conv == nil || conv.Issue == nil {
stats.Skipped++
continue
}
if existing == nil {
if localID := strings.TrimSpace(conv.Issue.ID); localID != "" {
existing = localByID[localID]
}
}
// TransformIssue hook: description formatting, field normalization
if e.PullHooks != nil && e.PullHooks.TransformIssue != nil {
@ -326,32 +366,44 @@ func (e *Engine) doPull(ctx context.Context, opts SyncOptions) (*PullStats, erro
}
}
if existing != nil && pullIssueEqual(existing, conv.Issue, ref) {
stats.Skipped++
continue
}
if opts.DryRun {
if existing != nil {
e.msg("[dry-run] Would update local issue: %s - %s", extIssue.Identifier, extIssue.Title)
stats.Updated++
} else {
e.msg("[dry-run] Would import: %s - %s", extIssue.Identifier, extIssue.Title)
stats.Created++
}
continue
}
if existing != nil {
// Conflict-aware pull: skip updating issues that were locally
// modified since last sync. Conflict detection (Phase 2) will
// handle these per the configured resolution strategy.
// Without this guard, pull silently overwrites local changes
// before conflict detection can compare timestamps.
if lastSync != nil && existing.UpdatedAt.After(*lastSync) {
if lastSync != nil && existing.UpdatedAt.After(*lastSync) && !allowOverwriteIDs[existing.ID] {
stats.Skipped++
continue
}
// Update existing issue
updates := make(map[string]interface{})
updates["title"] = conv.Issue.Title
updates["description"] = conv.Issue.Description
updates["priority"] = conv.Issue.Priority
updates["status"] = string(conv.Issue.Status)
// Preserve metadata from tracker
if extIssue.Metadata != nil {
if raw, err := json.Marshal(extIssue.Metadata); err == nil {
updates["metadata"] = json.RawMessage(raw)
}
updates := buildPullIssueUpdates(existing, conv.Issue, ref)
if raw, ok := marshalTrackerMetadata(extIssue.Metadata); ok {
updates["metadata"] = raw
}
if err := e.Store.UpdateIssue(ctx, existing.ID, updates, e.Actor); err != nil {
if err := e.Store.RunInTransaction(ctx, fmt.Sprintf("bd: pull update %s", existing.ID), func(tx storage.Transaction) error {
if err := tx.UpdateIssue(ctx, existing.ID, updates, e.Actor); err != nil {
return err
}
return syncIssueLabels(ctx, tx, existing.ID, conv.Issue.Labels, e.Actor)
}); err != nil {
e.warn("Failed to update %s: %v", existing.ID, err)
continue
}
@ -359,10 +411,8 @@ func (e *Engine) doPull(ctx context.Context, opts SyncOptions) (*PullStats, erro
} else {
// Create new issue
conv.Issue.ExternalRef = strPtr(ref)
if extIssue.Metadata != nil {
if raw, err := json.Marshal(extIssue.Metadata); err == nil {
conv.Issue.Metadata = json.RawMessage(raw)
}
if raw, ok := marshalTrackerMetadata(extIssue.Metadata); ok {
conv.Issue.Metadata = raw
}
if err := e.Store.CreateIssue(ctx, conv.Issue, e.Actor); err != nil {
e.warn("Failed to create issue for %s: %v", extIssue.Identifier, err)
@ -385,6 +435,128 @@ func (e *Engine) doPull(ctx context.Context, opts SyncOptions) (*PullStats, erro
return stats, nil
}
func pullIssueEqual(local *types.Issue, remote *types.Issue, ref string) bool {
if local == nil || remote == nil {
return false
}
if local.Title != remote.Title ||
local.Description != remote.Description ||
local.Priority != remote.Priority ||
local.Status != remote.Status ||
local.IssueType != remote.IssueType ||
strings.TrimSpace(local.Assignee) != strings.TrimSpace(remote.Assignee) ||
!equalNormalizedStrings(local.Labels, remote.Labels) {
return false
}
localRef := ""
if local.ExternalRef != nil {
localRef = strings.TrimSpace(*local.ExternalRef)
}
return localRef == strings.TrimSpace(ref)
}
func buildPullIssueUpdates(existing *types.Issue, remote *types.Issue, ref string) map[string]interface{} {
updates := map[string]interface{}{
"title": remote.Title,
"description": remote.Description,
"priority": remote.Priority,
"status": string(remote.Status),
"issue_type": string(remote.IssueType),
"assignee": remote.Assignee,
}
trimmedRef := strings.TrimSpace(ref)
if trimmedRef == "" {
return updates
}
if existing.ExternalRef == nil || strings.TrimSpace(*existing.ExternalRef) != trimmedRef {
updates["external_ref"] = trimmedRef
}
return updates
}
func marshalTrackerMetadata(metadata interface{}) (json.RawMessage, bool) {
if metadata == nil {
return nil, false
}
raw, err := json.Marshal(metadata)
if err != nil {
return nil, false
}
return json.RawMessage(raw), true
}
func syncIssueLabels(ctx context.Context, tx storage.Transaction, issueID string, desired []string, actor string) error {
current, err := tx.GetLabels(ctx, issueID)
if err != nil {
return err
}
currentSet := normalizedStringSet(current)
desiredSet := normalizedStringSet(desired)
for label := range currentSet {
if _, ok := desiredSet[label]; ok {
continue
}
if err := tx.RemoveLabel(ctx, issueID, label, actor); err != nil {
return err
}
}
for label := range desiredSet {
if _, ok := currentSet[label]; ok {
continue
}
if err := tx.AddLabel(ctx, issueID, label, actor); err != nil {
return err
}
}
return nil
}
func equalNormalizedStrings(a, b []string) bool {
an := normalizedStringSlice(a)
bn := normalizedStringSlice(b)
if len(an) != len(bn) {
return false
}
for i := range an {
if an[i] != bn[i] {
return false
}
}
return true
}
func normalizedStringSet(values []string) map[string]struct{} {
result := make(map[string]struct{}, len(values))
for _, value := range values {
value = strings.TrimSpace(value)
if value == "" {
continue
}
result[value] = struct{}{}
}
return result
}
func normalizedStringSlice(values []string) []string {
set := normalizedStringSet(values)
result := make([]string, 0, len(set))
for value := range set {
result = append(result, value)
}
sort.Strings(result)
return result
}
func parseSyncTime(value string) (time.Time, error) {
if value == "" {
return time.Time{}, fmt.Errorf("empty sync timestamp")
}
if parsed, err := time.Parse(time.RFC3339Nano, value); err == nil {
return parsed, nil
}
return time.Parse(time.RFC3339, value)
}
// doPush exports beads issues to the external tracker.
func (e *Engine) doPush(ctx context.Context, opts SyncOptions, skipIDs, forceIDs map[string]bool) (*PushStats, error) {
ctx, span := syncTracer.Start(ctx, "tracker.push",
@ -424,6 +596,55 @@ func (e *Engine) doPush(ctx context.Context, opts SyncOptions, skipIDs, forceIDs
}
}
if batchTracker, ok := e.Tracker.(BatchPushTracker); ok {
pushIssues, skipped := e.collectBatchPushIssues(issues, opts, descendantSet, skipIDs, forceIDs)
stats.Skipped += skipped
if len(pushIssues) == 0 {
return stats, nil
}
if opts.DryRun {
if dryRunner, ok := e.Tracker.(BatchPushDryRunner); ok {
batchResult, err := dryRunner.BatchPushDryRun(ctx, pushIssues, forceIDs)
if err != nil {
return nil, fmt.Errorf("previewing batch push: %w", err)
}
e.renderBatchDryRun(pushIssues, batchResult)
stats.Created += len(batchResult.Created)
stats.Updated += len(batchResult.Updated)
stats.Skipped += len(batchResult.Skipped)
stats.Errors += len(batchResult.Errors)
stats.Warnings = append(stats.Warnings, batchResult.Warnings...)
for _, item := range batchResult.Errors {
if item.LocalID != "" {
e.warn("Failed to preview push %s in %s: %s", item.LocalID, e.Tracker.DisplayName(), item.Message)
continue
}
e.warn("Failed to preview pushes in %s: %s", e.Tracker.DisplayName(), item.Message)
}
return stats, nil
}
} else {
batchResult, err := batchTracker.BatchPush(ctx, pushIssues, forceIDs)
if err != nil {
return nil, fmt.Errorf("batch pushing issues: %w", err)
}
e.applyBatchPushResult(ctx, batchResult)
stats.Created += len(batchResult.Created)
stats.Updated += len(batchResult.Updated)
stats.Skipped += len(batchResult.Skipped)
stats.Errors += len(batchResult.Errors)
stats.Warnings = append(stats.Warnings, batchResult.Warnings...)
for _, item := range batchResult.Errors {
if item.LocalID != "" {
e.warn("Failed to push %s in %s: %s", item.LocalID, e.Tracker.DisplayName(), item.Message)
continue
}
e.warn("Failed to push issues in %s: %s", e.Tracker.DisplayName(), item.Message)
}
return stats, nil
}
}
for _, issue := range issues {
// Limit to parent and its descendants if requested.
if descendantSet != nil && !descendantSet[issue.ID] {
@ -451,9 +672,10 @@ func (e *Engine) doPush(ctx context.Context, opts SyncOptions, skipIDs, forceIDs
}
extRef := derefStr(issue.ExternalRef)
willCreate := extRef == "" || !e.Tracker.IsExternalRef(extRef)
if opts.DryRun {
if extRef == "" {
if willCreate {
e.msg("[dry-run] Would create in %s: %s", e.Tracker.DisplayName(), issue.Title)
stats.Created++
} else {
@ -471,7 +693,7 @@ func (e *Engine) doPush(ctx context.Context, opts SyncOptions, skipIDs, forceIDs
pushIssue = &copy
}
if extRef == "" || !e.Tracker.IsExternalRef(extRef) {
if willCreate {
// Create in external tracker
created, err := e.Tracker.CreateIssue(ctx, pushIssue)
if err != nil {
@ -532,8 +754,84 @@ func (e *Engine) doPush(ctx context.Context, opts SyncOptions, skipIDs, forceIDs
return stats, nil
}
func (e *Engine) collectBatchPushIssues(issues []*types.Issue, opts SyncOptions, descendantSet, skipIDs, forceIDs map[string]bool) ([]*types.Issue, int) {
pushIssues := make([]*types.Issue, 0, len(issues))
skipped := 0
for _, issue := range issues {
if descendantSet != nil && !descendantSet[issue.ID] {
skipped++
continue
}
if !e.shouldPushIssue(issue, opts) {
skipped++
continue
}
if e.PushHooks != nil && e.PushHooks.ShouldPush != nil && !e.PushHooks.ShouldPush(issue) {
skipped++
continue
}
if skipIDs[issue.ID] {
skipped++
continue
}
extRef := derefStr(issue.ExternalRef)
willCreate := extRef == "" || !e.Tracker.IsExternalRef(extRef)
if !willCreate && opts.CreateOnly && !forceIDs[issue.ID] {
skipped++
continue
}
pushIssues = append(pushIssues, e.formatPushIssue(issue))
}
return pushIssues, skipped
}
func (e *Engine) formatPushIssue(issue *types.Issue) *types.Issue {
if e.PushHooks == nil || e.PushHooks.FormatDescription == nil {
return issue
}
copy := *issue
copy.Description = e.PushHooks.FormatDescription(issue)
return &copy
}
func (e *Engine) applyBatchPushResult(ctx context.Context, result *BatchPushResult) {
if result == nil {
return
}
items := append(append([]BatchPushItem(nil), result.Created...), result.Updated...)
for _, item := range items {
if item.LocalID == "" || strings.TrimSpace(item.ExternalRef) == "" {
continue
}
updates := map[string]interface{}{"external_ref": strings.TrimSpace(item.ExternalRef)}
if err := e.Store.UpdateIssue(ctx, item.LocalID, updates, e.Actor); err != nil {
e.warn("Failed to update external_ref for %s: %v", item.LocalID, err)
}
}
}
func (e *Engine) renderBatchDryRun(issues []*types.Issue, result *BatchPushResult) {
if result == nil {
return
}
titles := make(map[string]string, len(issues))
for _, issue := range issues {
if issue == nil || issue.ID == "" {
continue
}
titles[issue.ID] = issue.Title
}
for _, item := range result.Created {
e.msg("[dry-run] Would create in %s: %s", e.Tracker.DisplayName(), titles[item.LocalID])
}
for _, item := range result.Updated {
e.msg("[dry-run] Would update in %s: %s", e.Tracker.DisplayName(), titles[item.LocalID])
}
}
// resolveConflicts applies the configured conflict resolution strategy.
func (e *Engine) resolveConflicts(ctx context.Context, opts SyncOptions, conflicts []Conflict, skipIDs, forceIDs map[string]bool) {
func (e *Engine) resolveConflicts(opts SyncOptions, conflicts []Conflict, skipIDs, forceIDs, allowPullOverwriteIDs map[string]bool) {
for _, c := range conflicts {
switch opts.ConflictResolution {
case ConflictLocal:
@ -542,7 +840,7 @@ func (e *Engine) resolveConflicts(ctx context.Context, opts SyncOptions, conflic
case ConflictExternal:
skipIDs[c.IssueID] = true
e.reimportIssue(ctx, c)
allowPullOverwriteIDs[c.IssueID] = true
e.msg("Conflict on %s: keeping external version", c.IssueID)
default: // ConflictTimestamp or unset
@ -551,7 +849,7 @@ func (e *Engine) resolveConflicts(ctx context.Context, opts SyncOptions, conflic
e.msg("Conflict on %s: local is newer, pushing", c.IssueID)
} else {
skipIDs[c.IssueID] = true
e.reimportIssue(ctx, c)
allowPullOverwriteIDs[c.IssueID] = true
e.msg("Conflict on %s: external is newer, importing", c.IssueID)
}
}

View file

@ -66,6 +66,24 @@ type mockTracker struct {
fieldMapper FieldMapper
}
type mockExternalRefTracker struct {
*mockTracker
buildRef func(*TrackerIssue) string
extract func(string) string
isRef func(string) bool
}
type mockBatchTracker struct {
*mockTracker
batchResult *BatchPushResult
batchDryRun *BatchPushResult
batchErr error
batchCalls int
batchDryCalls int
batchIssues []*types.Issue
batchForceIDs map[string]bool
}
func newMockTracker(name string) *mockTracker {
return &mockTracker{
name: name,
@ -74,6 +92,27 @@ func newMockTracker(name string) *mockTracker {
}
}
func (m *mockExternalRefTracker) IsExternalRef(ref string) bool {
if m.isRef != nil {
return m.isRef(ref)
}
return m.mockTracker.IsExternalRef(ref)
}
func (m *mockExternalRefTracker) ExtractIdentifier(ref string) string {
if m.extract != nil {
return m.extract(ref)
}
return m.mockTracker.ExtractIdentifier(ref)
}
func (m *mockExternalRefTracker) BuildExternalRef(issue *TrackerIssue) string {
if m.buildRef != nil {
return m.buildRef(issue)
}
return m.mockTracker.BuildExternalRef(issue)
}
func (m *mockTracker) Name() string { return m.name }
func (m *mockTracker) DisplayName() string { return m.name }
func (m *mockTracker) ConfigPrefix() string { return m.name }
@ -93,6 +132,32 @@ func (m *mockTracker) BuildExternalRef(issue *TrackerIssue) string {
return fmt.Sprintf("https://%s.test/%s", m.name, issue.Identifier)
}
func (m *mockBatchTracker) BatchPush(_ context.Context, issues []*types.Issue, forceIDs map[string]bool) (*BatchPushResult, error) {
if m.batchErr != nil {
return nil, m.batchErr
}
m.batchCalls++
m.batchIssues = append(m.batchIssues, issues...)
m.batchForceIDs = forceIDs
if m.batchResult != nil {
return m.batchResult, nil
}
return &BatchPushResult{}, nil
}
func (m *mockBatchTracker) BatchPushDryRun(_ context.Context, issues []*types.Issue, forceIDs map[string]bool) (*BatchPushResult, error) {
if m.batchErr != nil {
return nil, m.batchErr
}
m.batchDryCalls++
m.batchIssues = append(m.batchIssues, issues...)
m.batchForceIDs = forceIDs
if m.batchDryRun != nil {
return m.batchDryRun, nil
}
return &BatchPushResult{}, nil
}
func (m *mockTracker) FetchIssues(_ context.Context, _ FetchOptions) ([]TrackerIssue, error) {
if m.fetchErr != nil {
return nil, m.fetchErr
@ -138,7 +203,9 @@ func (m *mockTracker) UpdateIssue(_ context.Context, externalID string, issue *t
}
// mockMapper implements FieldMapper for testing.
type mockMapper struct{}
type mockMapper struct {
issueToBeads func(*TrackerIssue) *IssueConversion
}
func (m *mockMapper) PriorityToBeads(p interface{}) int {
if v, ok := p.(int); ok {
@ -159,6 +226,9 @@ func (m *mockMapper) IssueToTracker(issue *types.Issue) map[string]interface{} {
}
func (m *mockMapper) IssueToBeads(ti *TrackerIssue) *IssueConversion {
if m.issueToBeads != nil {
return m.issueToBeads(ti)
}
return &IssueConversion{
Issue: &types.Issue{
Title: ti.Title,
@ -170,6 +240,327 @@ func (m *mockMapper) IssueToBeads(ti *TrackerIssue) *IssueConversion {
}
}
func TestEnginePullMatchesExistingIssueByLocalID(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
defer store.Close()
issue := &types.Issue{
ID: "bd-local",
Title: "Local title",
Description: "Local description",
Status: types.StatusOpen,
IssueType: types.TypeTask,
Priority: 2,
UpdatedAt: time.Now().UTC().Add(-2 * time.Hour),
}
if err := store.CreateIssue(ctx, issue, "test-actor"); err != nil {
t.Fatalf("CreateIssue() error: %v", err)
}
tracker := newMockTracker("test")
tracker.issues = []TrackerIssue{{
ID: "EXT-1",
Identifier: "EXT-1",
URL: "https://test.test/EXT-1",
Title: "Remote title",
Description: "Remote description",
UpdatedAt: time.Now().UTC(),
}}
tracker.fieldMapper = &mockMapper{
issueToBeads: func(ti *TrackerIssue) *IssueConversion {
return &IssueConversion{
Issue: &types.Issue{
ID: "bd-local",
Title: ti.Title,
Description: ti.Description,
Priority: 2,
Status: types.StatusOpen,
IssueType: types.TypeTask,
},
}
},
}
engine := NewEngine(tracker, store, "test-actor")
result, err := engine.Sync(ctx, SyncOptions{Pull: true})
if err != nil {
t.Fatalf("Sync() error: %v", err)
}
if result.PullStats.Created != 0 || result.PullStats.Updated != 1 {
t.Fatalf("PullStats = %+v, want Created=0 Updated=1", result.PullStats)
}
updated, err := store.GetIssue(ctx, "bd-local")
if err != nil {
t.Fatalf("GetIssue() error: %v", err)
}
if updated.Title != "Remote title" || updated.Description != "Remote description" {
t.Fatalf("issue = %+v", updated)
}
}
func TestEnginePullSkipsNoopUpdate(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
defer store.Close()
extRef := "https://www.notion.so/32be5bf97fae804d9e07f93af6c79467"
issue := &types.Issue{
ID: "bd-local",
Title: "Remote title",
Description: "Remote description",
Status: types.StatusOpen,
IssueType: types.TypeTask,
Priority: 2,
Assignee: "Osamu",
Labels: []string{"alpha", "beta"},
ExternalRef: &extRef,
UpdatedAt: time.Now().UTC().Add(-2 * time.Hour),
}
if err := store.CreateIssue(ctx, issue, "test-actor"); err != nil {
t.Fatalf("CreateIssue() error: %v", err)
}
tracker := newMockTracker("test")
tracker.issues = []TrackerIssue{{
ID: "EXT-1",
Identifier: "EXT-1",
URL: extRef,
Title: "Remote title",
Description: "Remote description",
UpdatedAt: time.Now().UTC(),
}}
tracker.fieldMapper = &mockMapper{
issueToBeads: func(ti *TrackerIssue) *IssueConversion {
return &IssueConversion{
Issue: &types.Issue{
ID: "bd-local",
Title: ti.Title,
Description: ti.Description,
Priority: 2,
Status: types.StatusOpen,
IssueType: types.TypeTask,
Assignee: "Osamu",
Labels: []string{"beta", "alpha"},
},
}
},
}
engine := NewEngine(tracker, store, "test-actor")
result, err := engine.Sync(ctx, SyncOptions{Pull: true})
if err != nil {
t.Fatalf("Sync() error: %v", err)
}
if result.PullStats.Created != 0 || result.PullStats.Updated != 0 || result.PullStats.Skipped != 1 {
t.Fatalf("PullStats = %+v, want Created=0 Updated=0 Skipped=1", result.PullStats)
}
}
func TestEnginePullUpdatesLabelsOnExistingIssue(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
defer store.Close()
extRef := "https://www.notion.so/32be5bf97fae804d9e07f93af6c79467"
issue := &types.Issue{
ID: "bd-local",
Title: "Remote title",
Description: "Remote description",
Status: types.StatusOpen,
IssueType: types.TypeTask,
Priority: 2,
Assignee: "Osamu",
Labels: []string{"old-label"},
ExternalRef: &extRef,
UpdatedAt: time.Now().UTC().Add(-2 * time.Hour),
}
if err := store.CreateIssue(ctx, issue, "test-actor"); err != nil {
t.Fatalf("CreateIssue() error: %v", err)
}
tracker := newMockTracker("test")
tracker.issues = []TrackerIssue{{
ID: "EXT-1",
Identifier: "EXT-1",
URL: extRef,
Title: "Remote title",
Description: "Remote description",
Labels: []string{"new-a", "new-b"},
UpdatedAt: time.Now().UTC(),
}}
tracker.fieldMapper = &mockMapper{
issueToBeads: func(ti *TrackerIssue) *IssueConversion {
return &IssueConversion{
Issue: &types.Issue{
ID: "bd-local",
Title: ti.Title,
Description: ti.Description,
Priority: 2,
Status: types.StatusOpen,
IssueType: types.TypeTask,
Assignee: "Osamu",
Labels: append([]string(nil), ti.Labels...),
},
}
},
}
engine := NewEngine(tracker, store, "test-actor")
result, err := engine.Sync(ctx, SyncOptions{Pull: true})
if err != nil {
t.Fatalf("Sync() error: %v", err)
}
if result.PullStats.Updated != 1 {
t.Fatalf("PullStats = %+v, want Updated=1", result.PullStats)
}
labels, err := store.GetLabels(ctx, "bd-local")
if err != nil {
t.Fatalf("GetLabels() error: %v", err)
}
if !equalNormalizedStrings(labels, []string{"new-a", "new-b"}) {
t.Fatalf("labels = %v, want [new-a new-b]", labels)
}
}
func TestEnginePullDryRunTreatsLabelOnlyChangeAsUpdate(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
defer store.Close()
extRef := "https://www.notion.so/32be5bf97fae804d9e07f93af6c79467"
issue := &types.Issue{
ID: "bd-local",
Title: "Remote title",
Description: "Remote description",
Status: types.StatusOpen,
IssueType: types.TypeTask,
Priority: 2,
Assignee: "Osamu",
Labels: []string{"old-label"},
ExternalRef: &extRef,
UpdatedAt: time.Now().UTC().Add(-2 * time.Hour),
}
if err := store.CreateIssue(ctx, issue, "test-actor"); err != nil {
t.Fatalf("CreateIssue() error: %v", err)
}
tracker := newMockTracker("test")
tracker.issues = []TrackerIssue{{
ID: "EXT-1",
Identifier: "EXT-1",
URL: extRef,
Title: "Remote title",
Description: "Remote description",
Labels: []string{"new-label"},
UpdatedAt: time.Now().UTC(),
}}
tracker.fieldMapper = &mockMapper{
issueToBeads: func(ti *TrackerIssue) *IssueConversion {
return &IssueConversion{
Issue: &types.Issue{
ID: "bd-local",
Title: ti.Title,
Description: ti.Description,
Priority: 2,
Status: types.StatusOpen,
IssueType: types.TypeTask,
Assignee: "Osamu",
Labels: append([]string(nil), ti.Labels...),
},
}
},
}
engine := NewEngine(tracker, store, "test-actor")
result, err := engine.Sync(ctx, SyncOptions{Pull: true, DryRun: true})
if err != nil {
t.Fatalf("Sync() error: %v", err)
}
if result.PullStats.Updated != 1 || result.PullStats.Created != 0 {
t.Fatalf("PullStats = %+v, want Updated=1 Created=0", result.PullStats)
}
labels, err := store.GetLabels(ctx, "bd-local")
if err != nil {
t.Fatalf("GetLabels() error: %v", err)
}
if !equalNormalizedStrings(labels, []string{"old-label"}) {
t.Fatalf("labels = %v, want [old-label]", labels)
}
}
func TestEnginePullDoesNotTreatPreviousPullAsLocalConflict(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
defer store.Close()
extRef := "https://www.notion.so/32be5bf97fae804d9e07f93af6c79467"
issue := &types.Issue{
ID: "bd-local",
Title: "Local title",
Description: "Local description",
Status: types.StatusOpen,
IssueType: types.TypeTask,
Priority: 2,
ExternalRef: &extRef,
}
if err := store.CreateIssue(ctx, issue, "test-actor"); err != nil {
t.Fatalf("CreateIssue() error: %v", err)
}
tracker := newMockTracker("test")
tracker.fieldMapper = &mockMapper{
issueToBeads: func(ti *TrackerIssue) *IssueConversion {
return &IssueConversion{
Issue: &types.Issue{
ID: "bd-local",
Title: ti.Title,
Description: ti.Description,
Priority: 2,
Status: types.StatusOpen,
IssueType: types.TypeTask,
},
}
},
}
engine := NewEngine(tracker, store, "test-actor")
tracker.issues = []TrackerIssue{{
ID: "EXT-1",
Identifier: "EXT-1",
URL: extRef,
Title: "Remote title 1",
Description: "Remote description 1",
UpdatedAt: time.Now().UTC(),
}}
if _, err := engine.Sync(ctx, SyncOptions{Pull: true}); err != nil {
t.Fatalf("first Sync() error: %v", err)
}
tracker.issues = []TrackerIssue{{
ID: "EXT-1",
Identifier: "EXT-1",
URL: extRef,
Title: "Remote title 2",
Description: "Remote description 2",
UpdatedAt: time.Now().UTC().Add(time.Second),
}}
result, err := engine.Sync(ctx, SyncOptions{Pull: true})
if err != nil {
t.Fatalf("second Sync() error: %v", err)
}
if result.PullStats.Updated != 1 {
t.Fatalf("second PullStats = %+v, want Updated=1", result.PullStats)
}
updated, err := store.GetIssue(ctx, "bd-local")
if err != nil {
t.Fatalf("GetIssue() error: %v", err)
}
if updated.Description != "Remote description 2" {
t.Fatalf("description = %q, want %q", updated.Description, "Remote description 2")
}
}
func TestEnginePullOnly(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
@ -193,6 +584,12 @@ func TestEnginePullOnly(t *testing.T) {
if result.Stats.Created != 2 {
t.Errorf("Stats.Created = %d, want 2", result.Stats.Created)
}
if result.PullStats.Created != 2 || result.PullStats.Updated != 0 {
t.Errorf("PullStats = %+v, want Created=2 Updated=0", result.PullStats)
}
if result.PushStats.Created != 0 || result.PushStats.Updated != 0 {
t.Errorf("PushStats = %+v, want zero value", result.PushStats)
}
// Verify issues were stored
issues, err := store.SearchIssues(ctx, "", types.IssueFilter{})
@ -234,11 +631,179 @@ func TestEnginePushOnly(t *testing.T) {
if result.Stats.Created != 1 {
t.Errorf("Stats.Created = %d, want 1", result.Stats.Created)
}
if result.PushStats.Created != 1 || result.PushStats.Updated != 0 {
t.Errorf("PushStats = %+v, want Created=1 Updated=0", result.PushStats)
}
if result.PullStats.Created != 0 || result.PullStats.Updated != 0 {
t.Errorf("PullStats = %+v, want zero value", result.PullStats)
}
if len(tracker.created) != 1 {
t.Errorf("tracker.created = %d, want 1", len(tracker.created))
}
}
func TestEnginePushUsesBatchTrackerWhenAvailable(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
defer store.Close()
ref := strPtr("https://notion.so/existing")
issues := []*types.Issue{
{ID: "bd-batch-1", Title: "Create me", Status: types.StatusOpen, IssueType: types.TypeTask, Priority: 2},
{ID: "bd-batch-2", Title: "Update me", Status: types.StatusInProgress, IssueType: types.TypeFeature, Priority: 1, ExternalRef: ref},
}
for _, issue := range issues {
if err := store.CreateIssue(ctx, issue, "test-actor"); err != nil {
t.Fatalf("CreateIssue(%s) error: %v", issue.ID, err)
}
}
tracker := &mockBatchTracker{
mockTracker: newMockTracker("notion"),
batchResult: &BatchPushResult{
Created: []BatchPushItem{{LocalID: "bd-batch-1", ExternalRef: "https://notion.so/new-page"}},
Updated: []BatchPushItem{{LocalID: "bd-batch-2", ExternalRef: "https://notion.so/existing"}},
Warnings: []string{"Skipped unsupported Notion issue types: pm=1"},
},
}
engine := NewEngine(tracker, store, "test-actor")
result, err := engine.Sync(ctx, SyncOptions{Push: true})
if err != nil {
t.Fatalf("Sync() error: %v", err)
}
if tracker.batchCalls != 1 {
t.Fatalf("batchCalls = %d, want 1", tracker.batchCalls)
}
if len(tracker.created) != 0 || len(tracker.updated) != 0 {
t.Fatalf("fallback create/update path should not run: created=%d updated=%d", len(tracker.created), len(tracker.updated))
}
if result.PushStats.Created != 1 || result.PushStats.Updated != 1 {
t.Fatalf("PushStats = %+v", result.PushStats)
}
if len(result.Warnings) != 1 || !strings.Contains(result.Warnings[0], "pm=1") {
t.Fatalf("warnings = %#v", result.Warnings)
}
stored, err := store.GetIssue(ctx, "bd-batch-1")
if err != nil {
t.Fatalf("GetIssue() error: %v", err)
}
if stored.ExternalRef == nil || *stored.ExternalRef != "https://notion.so/new-page" {
t.Fatalf("external_ref = %#v, want batch-created ref", stored.ExternalRef)
}
storedUpdated, err := store.GetIssue(ctx, "bd-batch-2")
if err != nil {
t.Fatalf("GetIssue() error: %v", err)
}
if storedUpdated.ExternalRef == nil || *storedUpdated.ExternalRef != "https://notion.so/existing" {
t.Fatalf("updated external_ref = %#v, want batch-updated ref", storedUpdated.ExternalRef)
}
}
func TestEngineDryRunUsesBatchPreviewWhenAvailable(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
defer store.Close()
issue := &types.Issue{
ID: "bd-batch-preview",
Title: "Preview me",
Status: types.StatusOpen,
IssueType: types.TypeTask,
Priority: 2,
ExternalRef: strPtr("https://notion.so/existing"),
}
if err := store.CreateIssue(ctx, issue, "test-actor"); err != nil {
t.Fatalf("CreateIssue() error: %v", err)
}
tracker := &mockBatchTracker{
mockTracker: newMockTracker("notion"),
batchDryRun: &BatchPushResult{
Skipped: []string{"bd-batch-preview"},
Warnings: []string{"Skipped bd-batch-preview: Notion external_ref points outside the current target"},
},
}
engine := NewEngine(tracker, store, "test-actor")
var msgs []string
var warns []string
engine.OnMessage = func(msg string) { msgs = append(msgs, msg) }
engine.OnWarning = func(msg string) { warns = append(warns, msg) }
result, err := engine.Sync(ctx, SyncOptions{Push: true, DryRun: true})
if err != nil {
t.Fatalf("Sync() error: %v", err)
}
if tracker.batchDryCalls != 1 {
t.Fatalf("batchDryCalls = %d, want 1", tracker.batchDryCalls)
}
if tracker.batchCalls != 0 {
t.Fatalf("batchCalls = %d, want 0", tracker.batchCalls)
}
if result.PushStats.Updated != 0 || result.PushStats.Created != 0 {
t.Fatalf("PushStats = %+v, want zero create/update", result.PushStats)
}
if len(result.Warnings) != 1 || !strings.Contains(result.Warnings[0], "outside the current target") {
t.Fatalf("warnings = %#v", result.Warnings)
}
if len(msgs) != 0 {
t.Fatalf("msgs = %#v, want no create/update preview lines", msgs)
}
if len(warns) != 0 {
t.Fatalf("warns = %#v, want no immediate warning spam", warns)
}
stored, err := store.GetIssue(ctx, "bd-batch-preview")
if err != nil {
t.Fatalf("GetIssue() error: %v", err)
}
if stored.ExternalRef == nil || *stored.ExternalRef != "https://notion.so/existing" {
t.Fatalf("external_ref mutated in dry-run: %#v", stored.ExternalRef)
}
}
func TestEnginePushCountsCreateErrors(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
defer store.Close()
issue := &types.Issue{
ID: "bd-createerr1",
Title: "Local issue",
Status: types.StatusOpen,
IssueType: types.TypeTask,
Priority: 2,
}
if err := store.CreateIssue(ctx, issue, "test-actor"); err != nil {
t.Fatalf("CreateIssue() error: %v", err)
}
tracker := newMockTracker("test")
tracker.createErr = fmt.Errorf("push response reported 1 error")
engine := NewEngine(tracker, store, "test-actor")
result, err := engine.Sync(ctx, SyncOptions{Push: true})
if err != nil {
t.Fatalf("Sync() error: %v", err)
}
if result.Stats.Created != 0 {
t.Errorf("Stats.Created = %d, want 0", result.Stats.Created)
}
if result.Stats.Errors != 1 {
t.Errorf("Stats.Errors = %d, want 1", result.Stats.Errors)
}
stored, err := store.GetIssue(ctx, "bd-createerr1")
if err != nil {
t.Fatalf("GetIssue() error: %v", err)
}
if stored.ExternalRef != nil {
t.Fatalf("external_ref = %q, want nil", *stored.ExternalRef)
}
if len(tracker.created) != 0 {
t.Errorf("tracker.created = %d, want 0", len(tracker.created))
}
}
func TestEngineDryRun(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
@ -272,6 +837,135 @@ func TestEngineDryRun(t *testing.T) {
}
}
func TestEnginePullMatchesExistingIssueByExternalIdentifier(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
defer store.Close()
externalRef := strPtr("https://www.notion.so/0123456789abcdef0123456789abcdef")
issue := &types.Issue{
ID: "bd-notion1",
Title: "Existing issue",
Description: "old description",
Status: types.StatusOpen,
IssueType: types.TypeTask,
Priority: 2,
ExternalRef: externalRef,
}
if err := store.CreateIssue(ctx, issue, "test-actor"); err != nil {
t.Fatalf("CreateIssue() error: %v", err)
}
base := newMockTracker("notion")
base.issues = []TrackerIssue{
{
ID: "01234567-89ab-cdef-0123-456789abcdef",
Identifier: "01234567-89ab-cdef-0123-456789abcdef",
URL: "https://www.notion.so/0123456789abcdef0123456789abcdef",
Title: "Existing issue updated",
Description: "new description",
UpdatedAt: time.Now(),
},
}
tracker := &mockExternalRefTracker{
mockTracker: base,
buildRef: func(issue *TrackerIssue) string { return issue.URL },
extract: func(ref string) string {
ref = strings.TrimSpace(ref)
if strings.HasPrefix(ref, "https://www.notion.so/") {
ref = strings.TrimPrefix(ref, "https://www.notion.so/")
}
return strings.ToLower(strings.ReplaceAll(ref, "-", ""))
},
isRef: func(ref string) bool { return strings.HasPrefix(ref, "https://www.notion.so/") },
}
engine := NewEngine(tracker, store, "test-actor")
result, err := engine.Sync(ctx, SyncOptions{Pull: true})
if err != nil {
t.Fatalf("Sync() error: %v", err)
}
if result.Stats.Created != 0 {
t.Errorf("Stats.Created = %d, want 0", result.Stats.Created)
}
if result.Stats.Updated != 1 {
t.Errorf("Stats.Updated = %d, want 1", result.Stats.Updated)
}
issues, err := store.SearchIssues(ctx, "", types.IssueFilter{})
if err != nil {
t.Fatalf("SearchIssues() error: %v", err)
}
if len(issues) != 1 {
t.Fatalf("stored issues = %d, want 1", len(issues))
}
if issues[0].ExternalRef == nil || *issues[0].ExternalRef != "https://www.notion.so/0123456789abcdef0123456789abcdef" {
t.Fatalf("external_ref = %v, want canonical url", issues[0].ExternalRef)
}
if issues[0].Title != "Existing issue updated" {
t.Fatalf("title = %q, want updated title", issues[0].Title)
}
}
func TestEngineDryRunCountsExistingIssuesAsUpdates(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
defer store.Close()
extRef := strPtr("https://notion.test/EXT-1")
issue := &types.Issue{
ID: "bd-existing1",
Title: "Existing issue",
Status: types.StatusOpen,
IssueType: types.TypeTask,
Priority: 2,
ExternalRef: extRef,
}
if err := store.CreateIssue(ctx, issue, "test-actor"); err != nil {
t.Fatalf("CreateIssue() error: %v", err)
}
tracker := newMockTracker("notion")
tracker.issues = []TrackerIssue{
{
ID: "EXT-1",
Identifier: "EXT-1",
URL: "https://notion.test/EXT-1",
Title: "Existing issue updated",
UpdatedAt: time.Now(),
},
}
var messages []string
engine := NewEngine(tracker, store, "test-actor")
engine.OnMessage = func(msg string) { messages = append(messages, msg) }
result, err := engine.Sync(ctx, SyncOptions{Pull: true, DryRun: true})
if err != nil {
t.Fatalf("Sync() error: %v", err)
}
if result.PullStats.Created != 0 {
t.Errorf("PullStats.Created = %d, want 0", result.PullStats.Created)
}
if result.PullStats.Updated != 1 {
t.Errorf("PullStats.Updated = %d, want 1", result.PullStats.Updated)
}
joined := strings.Join(messages, "\n")
if strings.Contains(joined, "Would import") {
t.Fatalf("messages = %q, want update preview without import", joined)
}
if !strings.Contains(joined, "Would update local issue") {
t.Fatalf("messages = %q, want update preview", joined)
}
issues, err := store.SearchIssues(ctx, "", types.IssueFilter{})
if err != nil {
t.Fatalf("SearchIssues() error: %v", err)
}
if len(issues) != 1 {
t.Fatalf("stored issues = %d, want 1", len(issues))
}
}
func TestEngineExcludeTypes(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
@ -365,6 +1059,62 @@ func TestEngineConflictResolution(t *testing.T) {
}
}
func TestEngineSyncDoesNotCreateFalseConflictsAfterPull(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
defer store.Close()
lastSync := time.Now().UTC().Add(-1 * time.Hour)
if err := store.SetConfig(ctx, "test.last_sync", lastSync.Format(time.RFC3339)); err != nil {
t.Fatalf("SetConfig() error: %v", err)
}
issue := &types.Issue{
ID: "bd-sync1",
Title: "Local title",
Description: "Local description",
Status: types.StatusOpen,
IssueType: types.TypeTask,
Priority: 2,
ExternalRef: strPtr("https://test.test/EXT-1"),
UpdatedAt: lastSync.Add(-10 * time.Minute),
}
if err := store.CreateIssue(ctx, issue, "test-actor"); err != nil {
t.Fatalf("CreateIssue() error: %v", err)
}
tracker := newMockTracker("test")
tracker.issues = []TrackerIssue{
{
ID: "EXT-1",
Identifier: "EXT-1",
URL: "https://test.test/EXT-1",
Title: "Remote title",
Description: "Remote description",
UpdatedAt: lastSync.Add(30 * time.Minute),
},
}
engine := NewEngine(tracker, store, "test-actor")
result, err := engine.Sync(ctx, SyncOptions{Pull: true, Push: true})
if err != nil {
t.Fatalf("Sync() error: %v", err)
}
if result.Stats.Conflicts != 0 {
t.Fatalf("conflicts = %d, want 0", result.Stats.Conflicts)
}
if len(tracker.updated) != 0 {
t.Fatalf("tracker.updated = %d, want 0", len(tracker.updated))
}
stored, err := store.GetIssue(ctx, "bd-sync1")
if err != nil {
t.Fatalf("GetIssue() error: %v", err)
}
if stored.Title != "Remote title" {
t.Fatalf("title = %q, want remote title", stored.Title)
}
}
func TestEnginePullWithShouldImport(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
@ -598,6 +1348,121 @@ func TestEnginePushWithShouldPush(t *testing.T) {
}
}
func TestEnginePushWithShouldPushCanInspectLabels(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
defer store.Close()
for _, tc := range []struct {
id string
title string
label string
}{
{id: "bd-labelpush1", title: "Push labeled", label: "notion-sync"},
{id: "bd-labelskip1", title: "Skip unlabeled"},
} {
issue := &types.Issue{
ID: tc.id,
Title: tc.title,
Status: types.StatusOpen,
IssueType: types.TypeTask,
Priority: 2,
}
if err := store.CreateIssue(ctx, issue, "test-actor"); err != nil {
t.Fatalf("CreateIssue(%s) error: %v", tc.id, err)
}
if tc.label != "" {
if err := store.AddLabel(ctx, tc.id, tc.label, "test-actor"); err != nil {
t.Fatalf("AddLabel(%s) error: %v", tc.id, err)
}
}
}
tracker := newMockTracker("test")
engine := NewEngine(tracker, store, "test-actor")
engine.PushHooks = &PushHooks{
ShouldPush: func(issue *types.Issue) bool {
for _, label := range issue.Labels {
if label == "notion-sync" {
return true
}
}
return false
},
}
result, err := engine.Sync(ctx, SyncOptions{Push: true})
if err != nil {
t.Fatalf("Sync() error: %v", err)
}
if result.Stats.Created != 1 {
t.Errorf("Stats.Created = %d, want 1", result.Stats.Created)
}
if len(tracker.created) != 1 {
t.Fatalf("tracker.created = %d, want 1", len(tracker.created))
}
if tracker.created[0].ID != "bd-labelpush1" {
t.Fatalf("pushed issue ID = %q, want bd-labelpush1", tracker.created[0].ID)
}
}
func TestEngineDryRunTreatsForeignExternalRefAsCreate(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)
defer store.Close()
foreignRef := "https://github.com/example/repo/issues/1"
issue := &types.Issue{
ID: "bd-foreign1",
Title: "Mirror me to Notion",
Status: types.StatusOpen,
IssueType: types.TypeTask,
Priority: 2,
ExternalRef: &foreignRef,
}
if err := store.CreateIssue(ctx, issue, "test-actor"); err != nil {
t.Fatalf("CreateIssue() error: %v", err)
}
tracker := &mockExternalRefTracker{
mockTracker: newMockTracker("notion"),
isRef: func(ref string) bool { return strings.Contains(ref, "notion.so") },
}
engine := NewEngine(tracker, store, "test-actor")
var msgs []string
engine.OnMessage = func(msg string) { msgs = append(msgs, msg) }
result, err := engine.Sync(ctx, SyncOptions{Push: true, DryRun: true})
if err != nil {
t.Fatalf("Sync() error: %v", err)
}
if result.Stats.Created != 1 {
t.Fatalf("Stats.Created = %d, want 1", result.Stats.Created)
}
if result.Stats.Updated != 0 {
t.Fatalf("Stats.Updated = %d, want 0", result.Stats.Updated)
}
joined := strings.Join(msgs, "\n")
if !strings.Contains(joined, "Would create in notion: Mirror me to Notion") {
t.Fatalf("messages = %q, want create message", joined)
}
if strings.Contains(joined, "Would update in notion") {
t.Fatalf("messages = %q, did not expect update message", joined)
}
issues, err := store.SearchIssues(ctx, "", types.IssueFilter{})
if err != nil {
t.Fatalf("SearchIssues() error: %v", err)
}
if len(issues) != 1 {
t.Fatalf("stored issues = %d, want 1", len(issues))
}
if issues[0].ExternalRef == nil || *issues[0].ExternalRef != foreignRef {
t.Fatalf("external_ref = %v, want %q", issues[0].ExternalRef, foreignRef)
}
}
func TestEnginePushWithContentEqual(t *testing.T) {
ctx := context.Background()
store := newTestStore(t)

View file

@ -58,6 +58,24 @@ type IssueTracker interface {
BuildExternalRef(issue *TrackerIssue) string
}
// BatchPushTracker is an optional capability for trackers that can export
// multiple issues in one remote call.
type BatchPushTracker interface {
BatchPush(ctx context.Context, issues []*types.Issue, forceIDs map[string]bool) (*BatchPushResult, error)
}
// BatchPushDryRunner is an optional capability for trackers that can preview
// batch push decisions without mutating the remote system.
type BatchPushDryRunner interface {
BatchPushDryRun(ctx context.Context, issues []*types.Issue, forceIDs map[string]bool) (*BatchPushResult, error)
}
// PullStatsProvider is an optional capability for trackers that can report
// raw fetch counts separately from incremental pull candidates.
type PullStatsProvider interface {
LastPullStats() (queried int, candidates int)
}
// FieldMapper handles bidirectional conversion of issue fields between
// an external tracker and beads. Each tracker provides its own mapper.
type FieldMapper interface {

View file

@ -91,11 +91,13 @@ type SyncOptions struct {
// SyncResult is the complete result of a sync operation.
type SyncResult struct {
Success bool `json:"success"`
Stats SyncStats `json:"stats"`
LastSync string `json:"last_sync,omitempty"` // RFC3339 timestamp
Error string `json:"error,omitempty"`
Warnings []string `json:"warnings,omitempty"`
Success bool `json:"success"`
Stats SyncStats `json:"stats"`
LastSync string `json:"last_sync,omitempty"` // RFC3339 timestamp
Error string `json:"error,omitempty"`
Warnings []string `json:"warnings,omitempty"`
PullStats PullStats `json:"-"`
PushStats PushStats `json:"-"`
}
// SyncStats accumulates sync statistics.
@ -111,6 +113,8 @@ type SyncStats struct {
// PullStats tracks pull operation results.
type PullStats struct {
Queried int
Candidates int
Created int
Updated int
Skipped int
@ -120,10 +124,32 @@ type PullStats struct {
// PushStats tracks push operation results.
type PushStats struct {
Created int
Updated int
Skipped int
Errors int
Created int
Updated int
Skipped int
Errors int
Warnings []string
}
// BatchPushItem describes one local issue handled by a tracker batch push.
type BatchPushItem struct {
LocalID string
ExternalRef string
}
// BatchPushError describes one issue-level failure from a tracker batch push.
type BatchPushError struct {
LocalID string
Message string
}
// BatchPushResult is the normalized result of a tracker batch push.
type BatchPushResult struct {
Created []BatchPushItem
Updated []BatchPushItem
Skipped []string
Errors []BatchPushError
Warnings []string
}
// Conflict represents a bidirectional modification conflict.