{"slug":"developers/HOW_TO_USE","title":"How to Build on IntegrateWise Platform","section":"developers","sectionLabel":"Developers","status":"unclassified","type":"document","path":"developers/HOW_TO_USE.mdx","bytes":15365,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nGuide for external frontend apps consuming the platform.\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    Your Frontend App                        │\n├─────────────────────────────────────────────────────────────┤\n│  React / Next.js / Vue / Svelte / React Native / Flutter   │\n└─────────────────────────────────────────────────────────────┘\n                            │\n                            ▼\n┌─────────────────────────────────────────────────────────────┐\n│              IntegrateWise Gateway                          │\n│         INTEGRATEWISE_GATEWAY_URL                            │\n├─────────────────────────────────────────────────────────────┤\n│  Auth (JWT) → Tenant Resolution → Rate Limiting → Routing  │\n└─────────────────────────────────────────────────────────────┘\n                            │\n            ┌───────────────┼───────────────┐\n            ▼               ▼               ▼\n      ┌──────────┐   ┌──────────┐   ┌──────────┐\n      │Connector │   │  Spine   │   │Capability│\n      │  APIs    │   │  Data    │   │  Engine  │\n      └──────────┘   └──────────┘   └──────────┘\n            │               │               │\n            ▼               ▼               ▼\n      Salesforce      Accounts        Execute\n      HubSpot         Contacts        Actions\n      Slack           Deals           Govern\n      GitHub          Tasks           Approve\n```\n\n---\n\n## Quick Start (5 minutes)\n\nSet `INTEGRATEWISE_GATEWAY_URL` to the Gateway origin for the intended\nenvironment. Use the Gateway only; platform workers and services are not direct\nclient endpoints.\n\n### 0. Discover Packages, Services, and Endpoints\n\nNo credentials are needed to discover the read-only public contract:\n\n```bash\ncurl \"$INTEGRATEWISE_GATEWAY_URL/api/v1/platform\"\ncurl \"$INTEGRATEWISE_GATEWAY_URL/api/v1/platform/packages\"\ncurl \"$INTEGRATEWISE_GATEWAY_URL/api/v1/platform/services\"\ncurl \"$INTEGRATEWISE_GATEWAY_URL/api/v1/platform/openapi.json\"\n```\n\nThe response describes only Gateway-facing contracts. It does not publish\nservice bindings, direct worker URLs, provider credentials, or tenant data.\n\n### 1. Get Credentials\n\n```bash\n# Sign in via Clerk\nopen \"https://accounts.integratewise.ai/sign-in\"\n\n# After login, you get:\nexport INTEGRATEWISE_API_TOKEN=\"eyJhbGci...\"\nexport INTEGRATEWISE_TENANT_ID=\"tenant_abc123\"\n```\n\n### 2. Verify Gateway Reachability\n\n```bash\ncurl \"$INTEGRATEWISE_GATEWAY_URL/health\"\n\n# → {\"status\":\"ok\",\"service\":\"gateway\",\"ts\":...}\n```\n\n### 3. Fetch Data\n\n```bash\n# Get your workspace data\ncurl -H \"Authorization: Bearer $INTEGRATEWISE_API_TOKEN\" \\\n     -H \"x-tenant-id: $INTEGRATEWISE_TENANT_ID\" \\\n     \"$INTEGRATEWISE_GATEWAY_URL/api/v1/workspace/projection/SALES\"\n\n# → Full workbench with accounts, contacts, deals, tasks\n```\n\n---\n\n## Use Cases\n\n### 1. CRM Dashboard\n\nBuild a sales dashboard showing accounts, deals, and pipeline.\n\n```typescript\n// Fetch sales workbench\nconst workbench = await fetch(\n  \"https://gateway.dev.integratewise.ai/api/v1/workspace/projection/SALES\",\n  {\n    headers: {\n      \"Authorization\": `Bearer ${token}`,\n      \"x-tenant-id\": tenantId,\n    },\n  }\n).then(r => r.json());\n\n// Render\nconst accounts = workbench.entities.account || [];\nconst deals = workbench.entities.deal || [];\nconst tasks = workbench.entities.task || [];\n\nreturn (\n  <Dashboard>\n    <Metrics accounts={accounts.length} deals={deals.length} />\n    <AccountList accounts={accounts} />\n    <DealPipeline deals={deals} />\n    <TaskList tasks={tasks} />\n  </Dashboard>\n);\n```\n\n---\n\n### 2. Integration Marketplace\n\nLet users connect data sources (Salesforce, HubSpot, etc.).\n\n**Connectors are tenant-level assets.** Once connected, all apps share the same connection.\n\n```\n                    Tenant\n\n                       │\n\n               Connector Registry\n\n                       │\n\n      Salesforce (Connected)\n      Slack (Connected)\n      Gmail (Connected)\n      GitHub (Connected)\n\n           │           │          │\n\n     Customer Zero   Marketplace   Admin\n           │           │          │\n           └───────────┼──────────┘\n                       │\n                 Same Connections\n```\n\n```typescript\n// Get available connectors\nconst catalog = await fetch(\n  \"https://gateway.dev.integratewise.ai/api/v1/workspace/connectors/catalog\",\n  {\n    headers: {\n      \"Authorization\": `Bearer ${token}`,\n      \"x-tenant-id\": tenantId,\n    },\n  }\n).then(r => r.json());\n\n// Render marketplace\nreturn (\n  <Marketplace>\n    {catalog.connectors.map(connector => (\n      <ConnectorCard\n        key={connector.id}\n        name={connector.name}\n        category={connector.category}\n        status={connector.status}\n        onConnect={() => connectConnector(connector.id)}\n      />\n    ))}\n  </Marketplace>\n);\n\n// Connect a connector (OAuth flow)\nasync function connectConnector(connectorId: string) {\n  // 1. Start OAuth flow\n  const { auth_url } = await fetch(\n    `https://gateway.dev.integratewise.ai/api/v1/integrations/${connectorId}/authorize`,\n    {\n      method: \"POST\",\n      headers: {\n        \"Authorization\": `Bearer ${token}`,\n        \"x-tenant-id\": tenantId,\n      },\n    }\n  ).then(r => r.json());\n\n  // 2. Redirect user\n  window.location.href = auth_url;\n}\n```\n\n**What's shared at tenant level:**\n\n- OAuth tokens\n- Refresh tokens\n- Webhooks\n- Sync cursors\n- Provider schemas\n- Field mappings\n- Connector configuration\n\n**What's frontend-specific:**\n\n- UI preferences (layout, recent views, local state)\n\n---\n\n### 3. AI Assistant\n\nBuild an AI assistant that can query workspace data.\n\n```typescript\n// Ask AI to analyze data\nconst response = await fetch(\"https://gateway.dev.integratewise.ai/api/v1/brainstorm\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${token}`,\n    \"x-tenant-id\": tenantId,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    query: \"What are the top 5 deals this quarter?\",\n    context: { department: \"SALES\" },\n  }),\n}).then((r) => r.json());\n\n// response.insights = [\n//   { title: \"Top Deal\", value: \"Acme Corp - $120K\", confidence: 0.95 },\n//   ...\n// ]\n```\n\n---\n\n### 4. Automated Workflows\n\nExecute capabilities programmatically.\n\n```typescript\n// Read data from Salesforce\nconst accounts = await fetch(\"https://gateway.dev.integratewise.ai/api/v1/capabilities/resolve\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${token}`,\n    \"x-tenant-id\": tenantId,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    capability: \"salesforce:read-accounts\",\n    params: { limit: 100, filter: { industry: \"Technology\" } },\n  }),\n}).then((r) => r.json());\n\n// Process and write back\nfor (const account of accounts.result.accounts) {\n  await fetch(\"https://gateway.dev.integratewise.ai/api/v1/capabilities/resolve\", {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${token}`,\n      \"x-tenant-id\": tenantId,\n      \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify({\n      capability: \"salesforce:update-account\",\n      params: {\n        id: account.id,\n        fields: { last_reviewed: new Date().toISOString() },\n      },\n    }),\n  });\n}\n```\n\n---\n\n### 5. Mobile App\n\nReact Native integration.\n\n```typescript\n\nconst platform = createPlatformClient({\n  baseUrl: \"https://gateway.integratewise.ai\",\n  getAccessToken: () => AsyncStorage.getItem(\"token\"),\n});\n\nconst manifest = await platform.capability.resolve();\n\n// Render\nreturn (\n  <View>\n    <Text>Available actions: {manifest.capabilities.length}</Text>\n    <FlatList\n      data={manifest.capabilities}\n      keyExtractor={item => item.id}\n      renderItem={({ item }) => (\n        <CapabilityCard capability={item} />\n      )}\n    />\n  </View>\n);\n```\n\n---\n\n## React Hooks\n\n### useWorkbench\n\n```typescript\nfunction useWorkbench(token: string, tenantId: string, department: string) {\n  const [workbench, setWorkbench] = useState(null);\n  const [loading, setLoading] = useState(true);\n  const [error, setError] = useState(null);\n\n  useEffect(() => {\n    setLoading(true);\n    fetch(\n      `https://gateway.dev.integratewise.ai/api/v1/workspace/projection/${department}`,\n      {\n        headers: {\n          \"Authorization\": `Bearer ${token}`,\n          \"x-tenant-id\": tenantId,\n        },\n      }\n    )\n      .then(r => r.json())\n      .then(setWorkbench)\n      .catch(setError)\n      .finally(() => setLoading(false));\n  }, [token, tenantId, department]);\n\n  return { workbench, loading, error };\n}\n\n// Usage\nfunction Dashboard() {\n  const { workbench, loading } = useWorkbench(token, tenantId, \"SALES\");\n\n  if (loading) return <Spinner />;\n\n  return (\n    <div>\n      <h1>Sales Dashboard</h1>\n      <p>Accounts: {workbench.entities.account.length}</p>\n      <p>Deals: {workbench.entities.deal.length}</p>\n    </div>\n  );\n}\n```\n\n### useConnectors\n\n```typescript\nfunction useConnectors(token: string, tenantId: string) {\n  const [connectors, setConnectors] = useState([]);\n  const [loading, setLoading] = useState(true);\n\n  useEffect(() => {\n    fetch(\"https://gateway.dev.integratewise.ai/api/v1/workspace/connectors/catalog\", {\n      headers: {\n        Authorization: `Bearer ${token}`,\n        \"x-tenant-id\": tenantId,\n      },\n    })\n      .then((r) => r.json())\n      .then((data) => setConnectors(data.connectors))\n      .finally(() => setLoading(false));\n  }, [token, tenantId]);\n\n  const connect = async (connectorId: string) => {\n    const { auth_url } = await fetch(\n      `https://gateway.dev.integratewise.ai/api/v1/integrations/${connectorId}/authorize`,\n      {\n        method: \"POST\",\n        headers: {\n          Authorization: `Bearer ${token}`,\n          \"x-tenant-id\": tenantId,\n        },\n      }\n    ).then((r) => r.json());\n    window.location.href = auth_url;\n  };\n\n  return { connectors, loading, connect };\n}\n```\n\n### useCapabilities\n\n```typescript\nfunction useCapabilities(getAccessToken: () => Promise<string | null>) {\n  const [capabilities, setCapabilities] = useState([]);\n  const [loading, setLoading] = useState(true);\n\n  useEffect(() => {\n    createPlatformClient({\n      baseUrl: \"https://gateway.integratewise.ai\",\n      getAccessToken,\n    })\n      .capability.resolve()\n      .then((data) => setCapabilities(data.capabilities))\n      .finally(() => setLoading(false));\n  }, [getAccessToken]);\n\n  const prepare = async (capabilityId: string, input: Record<string, unknown>) => {\n    const client = createPlatformClient({\n      baseUrl: \"https://gateway.integratewise.ai\",\n      getAccessToken,\n    });\n    return client.capability.prepare(capabilityId, input);\n  };\n\n  return { capabilities, loading, prepare };\n}\n```\n\n---\n\n## Complete Example\n\n```typescript\n\nfunction IntegrateWiseApp({ token, tenantId }) {\n  const { workbench } = useWorkbench(token, tenantId, \"SALES\");\n  const { connectors, connect } = useConnectors(token, tenantId);\n  const { capabilities, execute } = useCapabilities(token, tenantId);\n\n  return (\n    <div className=\"app\">\n      \n      <header>\n        <h1>IntegrateWise</h1>\n        <p>Tenant: {tenantId}</p>\n      </header>\n\n      \n      <section>\n        <h2>Connected Integrations</h2>\n        {connectors\n          .filter(c => c.status === \"connected\")\n          .map(connector => (\n            <div key={connector.id}>\n              <span>{connector.name}</span>\n              <span>{connector.status}</span>\n            </div>\n          ))}\n        <button onClick={() => connect(\"salesforce\")}>\n          + Connect Salesforce\n        </button>\n      </section>\n\n      \n      <section>\n        <h2>Workspace Data</h2>\n        <div className=\"metrics\">\n          <div>Accounts: {workbench?.entities?.account?.length || 0}</div>\n          <div>Deals: {workbench?.entities?.deal?.length || 0}</div>\n          <div>People: {workbench?.entities?.person?.length || 0}</div>\n        </div>\n\n        <h3>Recent Deals</h3>\n        {workbench?.entities?.deal?.slice(0, 5).map(deal => (\n          <div key={deal.id}>\n            <span>{deal.name}</span>\n            <span>{deal.metadata.amount}</span>\n          </div>\n        ))}\n      </section>\n\n      \n      <section>\n        <h2>Available Actions</h2>\n        {capabilities.map(cap => (\n          <button\n            key={cap.id}\n            onClick={() => execute(cap.id, { limit: 10 })}\n          >\n            {cap.name}\n          </button>\n        ))}\n      </section>\n    </div>\n  );\n}\n```\n\n---\n\n## Environment Variables\n\n```bash\n# Required\nINTEGRATEWISE_API_TOKEN=eyJhbG...      # JWT from OAuth\nINTEGRATEWISE_TENANT_ID=tenant_abc123   # Your workspace tenant ID\n\n# Optional\nINTEGRATEWISE_BASE_URL=https://gateway.dev.integratewise.ai\nINTEGRATEWISE_USER_ID=user-123\nINTEGRATEWISE_ORG_ID=org-789\n```\n\n---\n\n## Error Handling\n\n```typescript\n\nasync function safeFetch<T>(fn: () => Promise<T>): Promise<T | null> {\n  try {\n    return await fn();\n  } catch (error) {\n    if (error instanceof ApiError) {\n      switch (error.status) {\n        case 401:\n          // Token expired — refresh or redirect to login\n          redirectToLogin();\n          break;\n        case 403:\n          // No permission — show error\n          showError(\"You don't have permission to access this resource\");\n          break;\n        case 429:\n          // Rate limited — retry after delay\n          const retryAfter = error.details?.retryAfter || 60;\n          await new Promise((r) => setTimeout(r, retryAfter * 1000));\n          return safeFetch(fn);\n        default:\n          console.error(error);\n      }\n    }\n    return null;\n  }\n}\n```\n\n---\n\n## Resources\n\n- **API Reference:** [docs/api/PLATFORM_API.md](./PLATFORM_API.md)\n- **SDK:** `npm install @integratewise/sdk`\n- **Spine Schema:** `npm install @integratewise/spine-schema`\n- **GitHub:** https://github.com/integratewise/integratewise-live\n- **Gateway:** set `INTEGRATEWISE_GATEWAY_URL` to the test or production Gateway origin.\n"}