docs: unify integration documentation#13
Merged
TheRealAgentK merged 12 commits intomasterfrom Mar 16, 2026
Merged
Conversation
- Update Python version requirement to 3.13+ - Replace vendored SDK references with pip package imports - Use ActionResult as required return type (matches SDK enforcement) - Add auth section covering custom (title), platform, and no-auth patterns - Add context.fetch() examples for GET, POST JSON, POST form - Add multi-file integration pattern with explicit config path - Add testing section with context.py and IntegrationResult pattern - Pin SDK dependency with ~= compatible release operator - Remove polling triggers (not supported in production) - Remove opinionated error handling guidance - Link to tooling repo for validation, billing.md, connected_account.md
- Add cross-references to main tutorial in both docs - Fix connected_account.md examples: context.http_client does not exist, replaced with context.fetch() matching SDK API and real integrations - Add comments explaining context.fetch() auto-injects auth for platform OAuth - Fix name-splitting logic in generic example to match real integration pattern - Update billing best practice: ActionResult is the standard return type regardless of billing support
…ps 1.4) - Create docs/manual/integration_structure.md: canonical reference for file structure, naming conventions, and config.json schema - Fix tutorial: modular integration imports changed from relative to absolute, matching all real integrations (Instagram, Facebook, Humanitix) - Fix tutorial: remove false 'minimum 10 characters' claim on action description (tooling doesn't enforce this)
- Create docs/manual/patterns.md: pagination (page-number, cursor, caller-
controlled), centralized API helpers (helpers.py module, static API class),
and multi-field custom auth patterns
- Fix credential access across all docs: context.auth['api_key'] is wrong,
credentials are nested under context.auth['credentials'] — verified against
SDK source (integration.py L280) and all real integrations
- Fix tutorial test example to use {'credentials': {'api_token': '...'}}
nesting, matching real test files (Freshdesk, Circle, Coda)
- config.json: name to kebab-case, identifier to title, add display_name, remove supports_connected_account, api_key format to password - api_fetch.py: remove fake connected account handler, remove print() statements, fix auth access, add return type annotations - requirements.txt: was empty UTF-16 BOM, now has SDK with ~= pin - tests: fix auth to pass flat (SDK validates against fields schema), add dependencies path back to context.py, use httpbin.org endpoints - Add __init__.py, README.md, icon.png (512x512 placeholder) - Remove .gitignore deletion (still needed for dependencies/) - Tutorial: fix test example to use flat auth, add note explaining production credentials nesting vs local testing
TheRealAgentK
requested review from
Hamish-taylor,
NinosMan and
ProRedCat
and removed request for
Hamish-taylor and
NinosMan
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 45bb446384
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Hamish-taylor
suggested changes
Mar 15, 2026
Contributor
Hamish-taylor
left a comment
Hamish-taylor
left a comment
There was a problem hiding this comment.
Just a few minoeR comments. I don't mind if you want to address these in other PR's like you mentioned this morning
Co-authored-by: Hamish Taylor <Hamisht11@gmail.com>
Hamish-taylor
approved these changes
Mar 16, 2026
Contributor
Hamish-taylor
left a comment
Hamish-taylor
left a comment
There was a problem hiding this comment.
Thanks for addressing those comments!
This was referenced Mar 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Consolidates integration documentation into the SDK repo as the single source of truth for "how to build an integration."
Part of a cross-repo documentation unification effort across integrations-sdk, autohive-integrations-tooling, integrations-autohive, and integrations.
Phase 1 — Complete ✅
docs/manual/building_your_first_integration.md— comprehensive tutorial covering config.json, actions, auth, context.fetch(), testing, multi-file patternsdocs/manual/billing.md— added cross-reference to main tutorial, clarified ActionResult as standard return typedocs/manual/connected_account.md— added cross-reference, fixed all code examples (replaced non-existentcontext.http_clientwithcontext.fetch()), added auth injection commentsdocs/manual/integration_structure.md— canonical reference for file structure, naming conventions, and full config.json schema. Fixed tutorial: modular imports changed from relative to absolute (matching real integrations), removed false "minimum 10 characters" claimdocs/manual/patterns.md— pagination (page-number, cursor, caller-controlled), centralized API helpers, multi-field custom auth. Fixedcontext.authcredential nesting across all docssamples/api-fetch/— kebab-case name,auth.title,display_nameon actions, properActionResultusage, added__init__.py/README.md/icon.png, SDK pin with~=samples/template/— clean starter template with config.json, action handler, tests, README. Replaces old templates in other reposdocs/apidocs/with pdoc 16.0.0README.md— doc index table, samples table, link to tooling repo for validation, removed stale Raygun sectionNext phases (separate PRs in other repos)
INTEGRATION_CHECKLIST.md,CONTRIBUTING.md), add cross-links to SDK