Integration Generator
Generate OAuth integration providers for Dafthunk: research provider APIs, create backend OAuth provider, add type definitions, configure frontend, and optionally create integration nodes.
Step 1: Research Provider and Register OAuth App
Research the OAuth flow:
- Use WebSearch/WebFetch to find official OAuth documentation
- Look for "OAuth 2.0", "Developer Apps", or "API Authentication" sections
- Identify authorization, token, and user info endpoints
- Note required scopes and token format (refresh support, expiration)
- Check token response structure and user info fields
Register OAuth application:
- Create a developer account on the provider's platform
- Register a new OAuth application/client
- Set redirect URI to:
http://localhost:3001/oauth/{provider-id}/connect(dev) - Note the generated Client ID and Client Secret
- Configure required scopes/permissions
Present for confirmation:
Based on {Provider} OAuth documentation:
**Provider**: {Provider Name}
**ID**: `{provider-id}` (kebab-case)
**Endpoints**:
- Authorization: https://...
- Token: https://...
- User Info: https://...
**Scopes**: scope1, scope2
**Token Refresh**: Supported/Not supported
**Token Expiration**: {expires_in seconds} / Never expires
**OAuth App Registered**:
- Client ID: {id}
- Client Secret: {secret}
- Redirect URI: http://localhost:3001/oauth/{provider-id}/connect
Ready to implement?
Step 2: Add Backend Types
File: apps/api/src/oauth/types.ts
/**
* {Provider} OAuth token response
*/
export interface {Provider}Token {
access_token: string;
refresh_token?: string;
expires_in?: number;
token_type: string;
scope?: string;
}
/**
* {Provider} user information
*/
export interface {Provider}User {
id: string | number;
email?: string;
name?: string;
// Add provider-specific fields
}
Step 3: Create Provider Class
File: apps/api/src/oauth/providers/{Provider}Provider.ts
import { OAuthProvider } from "../OAuthProvider";
import type { {Provider}Token, {Provider}User } from "../types";
export class {Provider}Provider extends OAuthProvider<{Provider}Token, {Provider}User> {
readonly name = "{provider-id}";
readonly displayName = "{Provider Name}";
readonly authorizationEndpoint = "https://...";
readonly tokenEndpoint = "https://...";
readonly userInfoEndpoint = "https://...";
readonly scopes = ["scope1", "scope2"];
readonly refreshEnabled = true; // false if no refresh support
readonly refreshEndpoint = "https://..."; // only if refreshEnabled
protected formatIntegrationName(user: {Provider}User): string {
return user.name || user.email || "User";
}
protected formatUserMetadata(user: {Provider}User): Record<string, any> {
return {
userId: user.id,
email: user.email,
name: user.name,
};
}
protected extractAccessToken(token: {Provider}Token): string {
return token.access_token;
}
protected extractRefreshToken(token: {Provider}Token): string | undefined {
return token.refresh_token;
}
protected extractExpiresAt(token: {Provider}Token): Date | undefined {
return token.expires_in
? new Date(Date.now() + token.expires_in * 1000)
: undefined;
}
}
Step 4: Register Backend Provider
File: apps/api/src/oauth/registry.ts
import { {Provider}Provider } from "./providers/{Provider}Provider";
const providers = {
// ... existing providers
"{provider-id}": new {Provider}Provider(),
} as const;
Step 5: Update Shared Types
File: packages/types/src/integration.ts
Add to IntegrationProvider union and OAUTH_PROVIDERS array:
export type IntegrationProvider =
| "existing-provider"
| "{provider-id}"
| "other-provider";
export const OAUTH_PROVIDERS: OAuthProvider[] = [
// ... existing providers
{
id: "{provider-id}",
name: "{Provider Name}",
description: "Connect your {Provider} account to...",
supportsOAuth: true,
oauthEndpoint: "/oauth/{provider-id}/connect",
},
];
Step 6: Create Frontend Provider
File: apps/web/src/integrations/providers/{provider-id}.ts
import {IconName} from "lucide-react/icons/{icon-name}";
import type { ProviderConfig } from "../types";
export const {provider}Provider: ProviderConfig = {
id: "{provider-id}",
name: "{Provider Name}",
description: "Connect your {Provider} account...",
icon: {IconName},
supportsOAuth: true,
oauthEndpoint: "/oauth/{provider-id}/connect",
successMessage: "{Provider} integration connected successfully",
};
Step 7: Register Frontend Provider
File: apps/web/src/integrations/providers/index.ts
import { {provider}Provider } from "./{provider-id}";
export const PROVIDER_REGISTRY: Record<IntegrationProvider, ProviderConfig> = {
// ... existing providers
"{provider-id}": {provider}Provider,
};
Step 8: Configure Environment
File: apps/api/.dev.vars
INTEGRATION_{PROVIDER}_CLIENT_ID=your_client_id
INTEGRATION_{PROVIDER}_CLIENT_SECRET=your_client_secret
Step 9: Update Integration Routes
File: apps/api/src/routes/integrations.ts
Add provider availability check:
if (
env.INTEGRATION_{PROVIDER}_CLIENT_ID &&
env.INTEGRATION_{PROVIDER}_CLIENT_SECRET
) {
availableProviders.push("{provider-id}");
}
Step 10: Test OAuth Flow
pnpm typecheck
pnpm dev
Navigate to integrations page, click "Connect {Provider}", complete OAuth flow, verify integration appears in list.
Optional: Create Integration Nodes
File: packages/runtime/src/nodes/{provider-id}/{action}-{provider-id}-node.ts
import { NodeExecution, NodeType } from "@dafthunk/types";
import { ExecutableNode, NodeContext } from "../../runtime/node-types";
export class {Action}{Provider}Node extends ExecutableNode {
public static readonly nodeType: NodeType = {
id: "{action}-{provider-id}",
name: "{Action} ({Provider})",
type: "{action}-{provider-id}",
description: "{Action description}",
tags: ["{Category}", "{Provider}"],
icon: "icon-name",
inputs: [
{
name: "integrationId",
type: "string",
description: "{Provider} integration to use",
hidden: true,
required: true,
},
// Add action-specific inputs
],
outputs: [
// Add action-specific outputs
],
};
async execute(context: NodeContext): Promise<NodeExecution> {
try {
const { integrationId } = context.inputs;
// Get integration (auto-refreshes token)
const integration = await context.getIntegration(integrationId);
// Call provider API
const response = await fetch("https://api.{provider}.com/...", {
method: "POST",
headers: {
Authorization: `Bearer ${integration.token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ /* request */ }),
});
if (!response.ok) {
return this.createErrorResult(`API call failed: ${await response.text()}`);
}
const data = await response.json();
return this.createSuccessResult({ /* outputs */ });
} catch (error) {
return this.createErrorResult(
error instanceof Error ? error.message : "Unknown error"
);
}
}
}
Register in apps/api/src/runtime/cloudflare-node-registry.ts:
import { {Action}{Provider}Node } from "./{provider-id}/{action}-{provider-id}-node";
this.registerImplementation({Action}{Provider}Node);
Optional: Create Frontend Widget
File: apps/web/src/components/workflow/widgets/integration-selector.tsx
export const {provider}Widget = createIntegrationWidget("{provider-id}", [
"{action1}-{provider-id}",
"{action2}-{provider-id}",
]);
Register in apps/web/src/components/workflow/widgets/index.ts:
import { {provider}Widget } from "./integration-selector";
export const widgetRegistry = {
...{provider}Widget,
};
Common Patterns
HTTP Basic Auth (e.g., Reddit):
protected getTokenHeaders(clientId: string, clientSecret: string): Record<string, string> {
const credentials = btoa(`${clientId}:${clientSecret}`);
return {
Authorization: `Basic ${credentials}`,
"Content-Type": "application/x-www-form-urlencoded",
};
}
No Token Expiration (e.g., GitHub):
readonly refreshEnabled = false;
protected extractExpiresAt(token: {Provider}Token): Date | undefined {
return undefined;
}
Custom Auth Parameters (e.g., Google):
protected customizeAuthUrl(url: URL): void {
url.searchParams.set("access_type", "offline");
}
Summary
After completion, list:
- Files created (backend types, provider, frontend config)
- Environment variables required
- OAuth flow test results
- Optional nodes/widgets created
Converted and distributed by TomeVault — claim your Tome and manage your conversions.