SDK Connectors

The DgiDgi SDK provides a comprehensive connector system for integrating external services with your tenant. This follows the BYOI (Bring Your Own Infrastructure) pattern where your data lives in your infrastructure.

Overview

Connectors allow tenants to:

• Connect their own GitHub/GitLab/Bitbucket repos
• Link their databases (Supabase, Neon, PlanetScale)
• Configure deployment targets (Vercel, Fly.io, Railway)
• Use their own AI providers (OpenAI, Anthropic)

Available Hooks

useConnectors

Fetch and manage tenant connectors.

import { useConnectors } from "@dgidgi-one/sdk";

function ConnectorsList() {
  const { connectors, actions } = useConnectors();

  if (connectors.isLoading) return <div>Loading...</div>;

  return (
    <div>
      {connectors.data?.map(connector => (
        <div key={connector.id}>
          <h3>{connector.providerName}</h3>
          <p>Status: {connector.status}</p>
          <p>Category: {connector.category}</p>
        </div>
      ))}
    </div>
  );
}

useConnectorProviders

Get available connector providers from the registry.

import { useConnectorProviders } from "@dgidgi-one/sdk";

function ProviderCatalog() {
  const { providers } = useConnectorProviders();

  // Group by category
  const grouped = providers.data?.reduce((acc, provider) => {
    const category = provider.category;
    if (!acc[category]) acc[category] = [];
    acc[category].push(provider);
    return acc;
  }, {});

  return (
    <div>
      {Object.entries(grouped || {}).map(([category, providers]) => (
        <div key={category}>
          <h2>{category}</h2>
          {providers.map(provider => (
            <button key={provider.id} onClick={() => connectProvider(provider.id)}>
              {provider.name}
            </button>
          ))}
        </div>
      ))}
    </div>
  );
}

Connecting a Provider

OAuth Flow

For OAuth providers (GitHub, Vercel, Slack, etc.):

import { useConnectors } from "@dgidgi-one/sdk";

function ConnectGitHub() {
  const { actions } = useConnectors();

  const handleConnect = async () => {
    // Initiates OAuth flow - redirects to provider
    await actions.startOAuth.mutateAsync({
      providerId: "github",
      returnUrl: window.location.href,
    });
  };

  return <button onClick={handleConnect}>Connect GitHub</button>;
}

API Key Providers

For API key-based providers:

import { useConnectors } from "@dgidgi-one/sdk";

function ConnectOpenAI() {
  const { actions } = useConnectors();
  const [apiKey, setApiKey] = useState("");

  const handleConnect = async () => {
    await actions.create.mutateAsync({
      providerId: "openai",
      credentials: { apiKey },
    });
  };

  return (
    <form onSubmit={handleConnect}>
      <input
        type="password"
        value={apiKey}
        onChange={e => setApiKey(e.target.value)}
        placeholder="OpenAI API Key"
      />
      <button type="submit">Connect</button>
    </form>
  );
}

Credential Modes

Connectors support different credential modes:

Mode	Description	Example Providers
hybrid	Platform provides defaults, tenant can override	GitHub, OpenAI, Vercel
tenant_managed	Tenant must provide credentials	Auth0, Clerk, Render

Using Your Own Credentials (BYOI)

Override platform defaults with your own:

import { useConnectors } from "@dgidgi-one/sdk";

function OverrideCredentials() {
  const { actions } = useConnectors();

  const handleOverride = async () => {
    await actions.setOverride.mutateAsync({
      providerId: "github",
      override: {
        clientId: "your-client-id",
        clientSecret: "your-client-secret",
      },
    });
  };

  return <button onClick={handleOverride}>Use My GitHub App</button>;
}

Check Credential Source

import { useConnectorCredentialInfo } from "@dgidgi-one/sdk";

function CredentialInfo({ providerId }) {
  const { data } = useConnectorCredentialInfo(providerId);

  return (
    <div>
      <p>Source: {data?.source}</p>
      <p>Configured: {data?.isConfigured ? "Yes" : "No"}</p>
      <p>Can Override: {data?.canOverride ? "Yes" : "No"}</p>
    </div>
  );
}

Provider Categories

Category	Providers
source_control	GitHub, GitLab, Bitbucket, Azure DevOps
database	Supabase, Neon, PlanetScale, MongoDB Atlas
deployment	Vercel, Netlify, Fly.io, Railway, Render
auth	Auth0, Clerk
ai	OpenAI, Anthropic, Groq
messaging	Slack, Discord
productivity	Notion, Linear
analytics	Google Analytics, PostHog
payment	Stripe
email	SendGrid, Resend
monitoring	Sentry, Datadog
domains	Cloudflare

Verifying Connections

Check if a connector is working:

import { useConnectors } from "@dgidgi-one/sdk";

function VerifyConnector({ connectorId }) {
  const { actions } = useConnectors();

  const handleVerify = async () => {
    const result = await actions.verify.mutateAsync(connectorId);
    console.log("Verification:", result.success ? "OK" : result.error);
  };

  return <button onClick={handleVerify}>Verify Connection</button>;
}

Project-Level Connectors

Enable connectors for specific projects:

import { useProjectConnectors } from "@dgidgi-one/sdk";

function ProjectConnectors({ projectId }) {
  const { connectors, actions } = useProjectConnectors(projectId);

  const enableForProject = async (tenantConnectorId) => {
    await actions.enable.mutateAsync({
      tenantConnectorId,
      config: {}, // Project-specific config
    });
  };

  return (
    <div>
      <h3>Enabled Connectors</h3>
      {connectors.data?.map(c => (
        <div key={c.id}>{c.providerName}</div>
      ))}
    </div>
  );
}

TypeScript Types

import type {
  TenantConnector,
  ProviderDefinition,
  ProviderCategory,
  CredentialMode,
  ConnectorStatus,
} from "@dgidgi-one/sdk";

// Connector statuses
type ConnectorStatus =
  | "active"       // Working
  | "pending"      // Awaiting setup
  | "error"        // Connection issue
  | "expired"      // Token expired
  | "disabled";    // Manually disabled

// Provider definition shape
interface ProviderDefinition {
  id: string;
  name: string;
  category: ProviderCategory;
  authType: "oauth2" | "api_key" | "jwt" | "none";
  capabilities: string[];
  credentialMode: CredentialMode;
  supportsTenantOverride: boolean;
}

Security

• All credentials are encrypted at rest (AES-256-GCM)
• Credentials are tenant-isolated (separate encryption keys)
• OAuth tokens are automatically refreshed
• API keys are never exposed in responses

Best Practices

1. Use OAuth when available - More secure than API keys
2. Verify connections - Always verify after connecting
3. Handle token refresh - SDK handles this automatically
4. Use project-level connectors - Scope access appropriately
5. Override for compliance - Use BYOI for audit requirements

Error Handling

import { useConnectors } from "@dgidgi-one/sdk";

function ConnectProvider() {
  const { actions } = useConnectors();

  const handleConnect = async () => {
    try {
      await actions.create.mutateAsync({ providerId: "github" });
    } catch (error) {
      if (error.status === 401) {
        console.error("Authentication failed");
      } else if (error.status === 409) {
        console.error("Connector already exists");
      } else {
        console.error("Connection failed:", error.message);
      }
    }
  };
}

Related

• Connector Overview - Architecture details
• Authentication - Auth patterns
• Security - Security best practices