Skip to content

feat(auth,client): surface integration type and guide past root-page error#32

Merged
4ier merged 1 commit into
mainfrom
feat/integration-type-hints
Apr 30, 2026
Merged

feat(auth,client): surface integration type and guide past root-page error#32
4ier merged 1 commit into
mainfrom
feat/integration-type-hints

Conversation

@4ier
Copy link
Copy Markdown
Owner

@4ier 4ier commented Apr 30, 2026

What

Two small nudges so first-time users don't have to parse a Notion paragraph to understand why root-page creation fails with an internal integration:

  1. notion auth status and notion auth doctor now print the integration type (internal / public) derived from bot.owner.type on /v1/users/me.
  2. When a validation_error matches the internal-integration root-page signature, client.errorHint appends a concrete workaround with the exact command to run next.

Why

Tracked in #25. The underlying API error is technically accurate but not actionable — this PR turns it into something copy-pasteable.

Before / After

notion auth status (internal integration)

Before:                        After:
✓ Authenticated                ✓ Authenticated
Workspace:      X              Workspace:      X
Bot:            cli            Bot:            cli
                               Integration:    internal
                               Root page:      not allowed (share a parent page)

Error wrap (internal integration hitting workspace root)

Error: validation_error: Provide a `parent.page_id` ...
  → Internal integrations can't create pages at the workspace root.
     Workaround: create (or pick) a parent page in the Notion UI, share
     it with this integration, then pass its ID as the parent:
         notion page create <shared-page-id> --title "..."
     To list pages shared with your integration: notion page list

Changes

  • cmd/auth.go: detectIntegrationType(botInfo) reads bot.owner.type; unknown/missing shapes return "" so the UI gracefully omits the lines. Used in both auth status and auth doctor.
  • internal/client/client.go: errorHint matches the Internal integrations aren't owned / insert_content signatures and returns a multi-line workaround.

Test plan

  • TestDetectIntegrationType: workspace-owned → internal, user-owned → public, missing/unknown shapes → empty.
  • Extended TestErrorHint cases for both signature variants.
  • Updated setupAuthTest fixture to include bot.owner so auth status tests still pass and now exercise the new branches.
  • Manual smoke against a real internal-integration account confirms both the auth status render and the live api POST /v1/pages error hint.

Closes #25

…error

The Notion API returns a technically-accurate but hard-to-action
validation error when an internal integration tries to create a page at
the workspace root:

    validation_error: Provide a parent.page_id or parent.database_id
    parameter to create a page, or use a public integration with
    insert_content capability. Internal integrations aren't owned by a
    single user, so creating workspace-level private pages is not
    supported.

Two small improvements so users don't have to parse that paragraph:

1. `notion auth status` and `notion auth doctor` now derive the
   integration type from bot.owner.type ("workspace" → internal,
   "user" → public) and print it. For internal integrations a follow-up
   line reminds the user they must share a parent page first.

2. client.errorHint matches the internal-integration validation_error
   signature and prints a concrete workaround with the exact next command:

       → Internal integrations can't create pages at the workspace root.
          Workaround: create (or pick) a parent page in the Notion UI,
          share it with this integration, then pass its ID as the parent:
              notion page create <shared-page-id> --title "..."
          To list pages shared with your integration: notion page list

Detection code is small (detectIntegrationType in cmd/auth.go) and
defensive: unknown or missing owner shape returns "" so pre-existing
response fixtures that don't include bot.owner still render fine.

Closes #25
@4ier 4ier force-pushed the feat/integration-type-hints branch from da46ac4 to bb6295f Compare April 30, 2026 05:00
@4ier 4ier merged commit 087048d into main Apr 30, 2026
4 checks passed
@4ier 4ier deleted the feat/integration-type-hints branch April 30, 2026 05:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clearer guidance when internal integration tries to create workspace-root page

1 participant