connect-oauth-service

Name: Flowstack
Author: Flowstack

recipesince 0.2.8

Let each user connect an OAuth service (github, reddit, twitter, strava, google) and work with their data in the app

Plane: oauth_connection · Requires: capability external_integration

Steps: 1. useConnections — Render connect UI gated on the provider's connection state; call connect('<provider>'); handle error_code on the result (consent_denied, state_mismatch, exchange_failed). 2. useAgent — With capabilities ['external_integration','data_access'], prompt the agent to fetch the user's data and UPSERT it into the provider's collection in the shape its connection contract declares. 3. useCollection — Read the provider's collection reactively ({ layer: 'user' }, refreshOnAgentComplete: true) — never parse chat text for data.

Examples

End-to-end example

import { useConnections, useAgent, useCollection } from '@flowstack/sdk';

export function GithubPanel() {
  const { connections, connect } = useConnections();
  const github = connections.find(c => c.provider === 'github');
  const { query } = useAgent(undefined, {
    capabilities: ['external_integration', 'data_access'],
  });
  const { documents: repos } = useCollection('github_repos', {
    layer: 'user',
    sort: { updated_at: -1 },
    refreshOnAgentComplete: true,
  });

  if (!github?.connected) {
    return <button onClick={() => connect('github')}>Connect GitHub</button>;
  }
  return (
    <>
      <button onClick={() => query('Sync my repos into github_repos (upsert on repo_id).')}>
        Sync repos
      </button>
      <ul>{repos.map(r => <li key={r.repo_id}>{r.full_name} ★{r.stars}</li>)}</ul>
    </>
  );
}

WarningOAuth connections are per-END-USER (popup flow) — never build an owner-key input form for these providers.

WarningGate every feature on live useConnections state; connection can be revoked between sessions.

WarningSync into layer 'user' collections and upsert on the provider's natural id — never blind-insert.

connect-oauth-service

Examples

See also