mirror of
https://github.com/ComposioHQ/composio.git
synced 2026-09-22 11:46:35 +08:00
d17a268d3f
Integration branch for the next docs release: a **sessions-first
documentation rewrite** — new and rewritten guides, example pages,
interactive components, and docs tooling — plus the supporting SDK
changes that the new docs describe.
The bulk of this PR is docs (~24k lines across ~150 commits); the SDK
changes (~5k lines) back the new guides.
## Documentation (the bulk)
- **Sessions-first restructure** — reorganized navigation and section
structure (incl. the "Sandbox (prev workbench)" section), with
v3-reorganization redirects so old URLs keep resolving.
- **Rewritten core guides** — quickstart, configuring sessions, triggers
(creating + subscribing to events), proxy-execute, toolkits
enable/disable, and common FAQ, rewritten in the house voice.
- **New example pages** — local-sandbox PR reviewer, daily standup bot,
and slack bot, with runnable build-ups.
- **New interactive components & diagrams** — triggers flow animation,
manage-connections visual, connection-refresh visual, and the
terminal-kit components.
- **Docs tooling** — a docs-graph link-graph connectivity checker,
search reprioritization (deprioritize legacy pages), and SDK-reference
regeneration.
## Supporting SDK changes
**`@composio/core` → 0.13.0 (minor)**
- `composio.sessions.create()` as the first-class sessions API
(`composio.create()` kept as an alias).
- **MCP is opt-in:** default `create()` / `use()` return native-tool
sessions (`SessionWithoutMcp`); pass `{ mcp: true }` to surface
`session.mcp`. _Migration: read `session.mcp` only after creating with
`{ mcp: true }`._
- `session.sandbox` is the canonical resolved config;
`session.workbench` kept as a deprecated alias. `sandbox` is the
preferred session-config key (`workbench` still accepted).
- `connectedAccounts.updateAcl()` graduated from experimental (alias
kept).
- `triggers.parse()` (parse + optionally verify an incoming webhook) and
`triggers.setWebhookSubscription()`.
**`@composio/experimental` → minor** — local-workbench helpers moved
onto the `@composio/experimental/workbench` subpath (out of
`@composio/core/experimental`), keeping the ~14 KB embedded Python
helper out of core. Plus the experimental Pi provider.
**`@composio/slim` → minor.**
**Python → 0.17.0** — mirrors the TS surface: `composio.sessions` mount
(`tool_router` deprecated), `triggers.parse()` /
`set_webhook_subscription()`, the `sandbox` config key, and
`connected_accounts.update_acl()`.
## Review response (#3664)
Addressed the `@composio/core` review:
- **Security:** `triggers.parse()` no longer fails open — a
present-but-empty `verifySecret` (e.g. unset `COMPOSIO_WEBHOOK_SECRET`)
now throws instead of silently skipping verification; omitting it stays
an explicit opt-out (both SDKs).
- Removed snake_case leakage from `transformWebhookSubscription` (+ the
index signature that allowed it).
- **Removed** the TS-only `connectedAccounts.link()` toolkit
auto-resolve (shipped with cancellability / orphaned-auth-config bugs
and was effectively undocumented; to be reintroduced properly later).
- Unified Python error types on `ValidationError`; added `mcp=True`
Python tests; fixed runtime-portability + error-type test assertions.
- Polished deprecation messages; fixed the backwards `/experimental`
`@deprecated` note and the `SessionWithMcp` JSDoc.
## Testing
- **TS:** `@composio/core` + `@composio/experimental` typecheck pass;
vitest green for the touched suites.
- **Python:** `test_tool_router.py` + `test_triggers.py` pass (161
tests).
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Kshitij Jhunjhunwala <kj@composio.dev>
Co-authored-by: Malay Vasa <malayvasa@gmail.com>
Co-authored-by: Sarah Simionescu <sarah@composio.dev>
Co-authored-by: Kshitij Jhunjhunwala <113939507+KJ-11@users.noreply.github.com>
124 lines
4.2 KiB
TypeScript
124 lines
4.2 KiB
TypeScript
import { CornerDownLeft } from 'lucide-react';
|
||
|
||
const NODES: {
|
||
label: string;
|
||
sub: string;
|
||
edge?: string;
|
||
accent?: boolean;
|
||
}[] = [
|
||
{ label: 'Your app', sub: 'user starts here' },
|
||
{
|
||
label: 'OAuth toolkit',
|
||
sub: 'Google, GitHub, …',
|
||
edge: 'user connects',
|
||
},
|
||
{
|
||
label: 'yourdomain.com',
|
||
sub: 'your proxy endpoint',
|
||
edge: 'redirects user',
|
||
accent: true,
|
||
},
|
||
{
|
||
label: 'backend.composio.dev',
|
||
sub: 'captures the token',
|
||
edge: 'forwards redirect',
|
||
},
|
||
];
|
||
|
||
/**
|
||
* WhiteLabelFlow — branded replacement for the OAuth redirect-proxy mermaid
|
||
* diagram on the white-labeling pages.
|
||
*
|
||
* Shows the browser redirect hop through your own domain: the user connects,
|
||
* the toolkit redirects to your proxy, your proxy forwards to Composio, and
|
||
* Composio sends the user back to your app. Your domain is brand-accented
|
||
* because it's the white-label point. The proxy never touches the token, only
|
||
* the browser redirect. Server component, light/dark via fd-* tokens.
|
||
*/
|
||
export function WhiteLabelFlow() {
|
||
return (
|
||
<div className="not-prose my-6 overflow-hidden rounded-sm border border-fd-border bg-fd-background">
|
||
{/* header strip */}
|
||
<div className="flex items-center justify-between border-b border-fd-border px-3 py-1.5 font-mono text-[10px] uppercase tracking-[0.06em] text-fd-foreground/45">
|
||
<span>oauth.redirect</span>
|
||
<span className="text-fd-foreground/55">browser hops only</span>
|
||
</div>
|
||
|
||
{/* the hops */}
|
||
<div className="grid items-stretch gap-px bg-fd-border md:grid-cols-4">
|
||
{NODES.map((node, i) => {
|
||
const last = i === NODES.length - 1;
|
||
return (
|
||
<div
|
||
key={node.label}
|
||
className="relative flex flex-col gap-2 bg-fd-background p-3"
|
||
>
|
||
{/* edge label sits above the node it points into */}
|
||
<span className="font-mono text-[9px] uppercase tracking-[0.06em] text-fd-foreground/40">
|
||
{node.edge ? `→ ${node.edge}` : ' '}
|
||
</span>
|
||
<div className="flex flex-1 items-center">
|
||
<div
|
||
className={
|
||
'relative w-full border p-3 ' +
|
||
(node.accent
|
||
? 'border-[var(--composio-brand)]/30 bg-[var(--composio-brand)]/[0.04]'
|
||
: 'border-fd-border bg-fd-card')
|
||
}
|
||
>
|
||
{node.accent && (
|
||
<span
|
||
aria-hidden="true"
|
||
className="pointer-events-none absolute inset-y-0 left-0 w-[2px] bg-[var(--composio-brand)]"
|
||
/>
|
||
)}
|
||
<code
|
||
className={
|
||
'block truncate font-mono text-[12px] font-medium ' +
|
||
(node.accent
|
||
? 'text-[var(--composio-brand)]'
|
||
: 'text-fd-foreground')
|
||
}
|
||
>
|
||
{node.label}
|
||
</code>
|
||
<span className="mt-1 block truncate font-mono text-[10px] text-fd-foreground/45">
|
||
{node.sub}
|
||
</span>
|
||
</div>
|
||
</div>
|
||
{!last && <Connector />}
|
||
</div>
|
||
);
|
||
})}
|
||
</div>
|
||
|
||
{/* the return hop */}
|
||
<div className="flex items-center justify-center gap-1.5 border-t border-fd-border px-3 py-2 font-mono text-[10px] text-fd-foreground/50">
|
||
<CornerDownLeft
|
||
aria-hidden="true"
|
||
className="size-3 text-[var(--composio-brand)]"
|
||
/>
|
||
Composio redirects the user back to{' '}
|
||
<code className="text-fd-foreground/70">your app</code>. Your proxy
|
||
never sees the token
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|
||
|
||
function Connector() {
|
||
return (
|
||
<div
|
||
aria-hidden="true"
|
||
className="pointer-events-none absolute z-10 hidden md:block"
|
||
style={{ right: '-7px', top: '50%' }}
|
||
>
|
||
<div className="flex items-center">
|
||
<span className="h-px w-3 bg-fd-border" />
|
||
<span className="size-0 border-y-[3px] border-l-[5px] border-y-transparent border-l-fd-border" />
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|