Skip to content

Commit

Permalink
fixed docs - overview & basic
Browse files Browse the repository at this point in the history
  • Loading branch information
@sohamganatra
sohamganatra committed Aug 17, 2024
1 parent bc76fcb commit 945fd43
Show file tree
Hide file tree
Showing 4 changed files with 203 additions and 388 deletions.
44 changes: 14 additions & 30 deletions docs/introduction/foundations/basic.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,17 @@
title: "Concepts at a Glance"
sidebarTitle: "At a Glance"
icon: "book"
description: "Platform's core concepts and functionalities."
description: "Core Platform Modules"
---

<CardGroup cols={3}>
<CardGroup cols={2}>

<Card color="#7bee0c" title="Entity" icon="users" href="./components/entity/entity-guide">
Entity could be Melissa, Sam, ABC Corp, etc
Entity is the user who is using your app Jessica or Melissa
</Card>

<Card color="#7bee0c" title="Integrations" icon="plug" href="./components/integrations/integration-guide">
Github Integration that that will ask Melissa for private repo permission
<Card color="#7bee0c" title="Accounts" icon="plug" href="./components/">
GitHub Connection Authorised for Jessica's account
</Card>


Expand All @@ -21,33 +21,17 @@ Send email via Gmail, Outlook, Sendgrid, etc
</Card>

<Card color="#7bee0c" title="Triggers" icon="webhook" href="./components/triggers/trigger-guide">
New Github Issue, Pull Request, Release, New Hubspot Ticket, Case etc
Webhooks on New Github Issue, Pull Request
</Card>

<Card color="#7bee0c" title="Custom Actions" icon="code" href="./components/actions/local-code">
Utilize credentials from a connected account to securely call specific API endpoints as part of a custom operation.
</Card>

<Card color="#7bee0c" title="Custom Tools" icon="puzzle-piece" href="./components/integrations/custom-integration">
Create your own tools on
</Card>
</CardGroup>


| Component | Description | Examples |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Entity | Entity represents the user and all accounts that belong to a specific user will have same entity id. &nbsp; [Learn More...](./components/entity/entity-guide) | Entity could be Melissa, Sam, ABC Corp, etc |
| ConnectedAccounts | Connections represent **link between your app and third-party platforms accounts of your user**. &nbsp; [Learn More...](./components/entity/entity-guide) | Melissa's Github account after completing auth with integration, Similarly Sam's Hubspot account. |
| Integrations | Integrations are customisable configurations (settings) that are used while creating a new connected account. &nbsp; [Learn More...](./components/integrations/integration-guide) | Github Integration that that will ask Melissa for private repo permission|
| Tools | Tools refer to the various applications or tools that can be integrated and used by your agents via Composio. &nbsp; [Learn More...](./components/tools/tool-guide) | Shell manager, Hubspot, Github, Slack & many others |
| Actions | Actions are tasks that can be performed by your agents. &nbsp; [Learn More...](./components/actions/action-guide) | Send email via Gmail, Send email via Outlook, Send email via Sendgrid, etc |
| Triggers | Triggers are predefined conditions that, when met, initiate webhooks to your agents. &nbsp; [Learn More...](./components/triggers/trigger-guide) | New Github Issue, New Github Pull Request, New Github Release, New Hubspot Ticket, New Hubspot Case, etc |


Let's get you started building with Composio! This section will get you familiar with Composio’s core concepts.

Goal of this section is to give you a brief walkthrough of each component and how they go together.

In next few pages, we can go through each component in detail. They will explain how to use each component in the code and what the expected flow should look like.

If you prefer something quicker, checkout [Quickstart Guide](../intro/quickstart)
| Component | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| Entity | Entity represents the user and all accounts that belong to a specific user will have same entity id. &nbsp; [Learn More...](./components/entity/entity-guide)
| Accounts | Connections represent **link between your app and third-party platforms accounts of your user**. &nbsp; [Learn More...](./components/entity/entity-guide)
| Tools | Tools refer to the various applications or tools that can be integrated and used by your agents via Composio. &nbsp; [Learn More...](./components/tools/tool-guide)
| Actions | Actions are tasks that can be performed by your agents. &nbsp; [Learn More...](./components/actions/action-guide)
| Triggers | Triggers are predefined conditions that, when met, initiate webhooks to your agents. &nbsp; [Learn More...](./components/triggers/trigger-guide)
| Integrations | Integrations are customisable configurations (settings) that are used while creating a new connected account. &nbsp; [Learn More...](./components/integrations/integration-guide)
155 changes: 45 additions & 110 deletions docs/introduction/foundations/components/entity/entity-guide.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,137 +2,50 @@
title: "🧑‍🤝‍🧑 Accounts/Entity"
sidebarTitle: "Accounts/Entity"
icon: "users"
description: "Manage all the connected accounts of your Users & Organizations 🧑‍🤝‍🧑 via entities"
description: "Manage all the connected accounts of your Users"
---

## Introduction to Entities

- Within Composio, an entity acts as a central hub representing either a user or an organization.
- This entity consolidates all their connected accounts, providing a unified view of their integrations.
- For instance, if you have million users connecting various accounts (Github, Hubspot, Slack, etc.) within your application,
each user would be represented as an individual entity.
- All the accounts linked by a user would then be neatly organized as connected accounts under their respective entity.
- **Each unique user** is represented by a **unique entity id**.
- If you have **two users, Jessica and Melissa**, they will have **unique entity ids**.

## Introduction to Connected Accounts
- When a user connects their account through any of our integrations, a `connected_account` object is created. This object securely stores authentication data such as access tokens and refresh tokens.
- When a user connects their account, a `connected_account` object is created.
- This object securely stores **authentication data** such as **access tokens and refresh tokens**.

### Create or get an entity

<Tabs>
<Tab title="Python">
<CodeGroup>
```python Create or get an entity
from composio import ComposioToolSet

toolset = ComposioToolSet(entity_id="default")

entity = toolset.get_entity(id='default')
```
</CodeGroup>
</Tab>

<Tab title="Javascript">
<CodeGroup>
```javascript Create or get an entity
import { Composio } from "composio-core";

const composio_client = new Composio({
apiKey: process.env.COMPOSIO_API_KEY,
});

const entity = composio_client.getEntity('user_email_id');
```
</CodeGroup>
</Tab>
</Tabs>

### Connect an account for an entity
<Tabs>
<Tab title="Via Dashboard">
The Composio dashboard primarily serves as a tool for quickly verifying your integration and trying new connections for initial testing.
For deploying in a production environment, utilize the SDK or API methods.
<div
style={{
width: '100%',
position: 'relative',
paddingTop: '56.25%',
}}>
<iframe
src="https://app.supademo.com/embed/cly1z8i4g0lwy149zfx6h4ee2"
frameBorder="0"
title="Direct Action Execution"
allow="clipboard-write"
webkitallowfullscreen="true"
mozallowfullscreen="true"
allowfullscreen
style={{
position: 'absolute',
top: 0,left: 0, width: '100%', height: '100%',
border: '3px solid #5E43CE',
borderRadius: '10px',
}}/>
</div>

</Tab>

<Tab title="CLI">
<CodeGroup>
```bash Adding a connection for an entity
composio add github -e default # replace `default` with the entity id

# you can also use -s to specify scopes ex. -s "repo,user"
# you can also use -i to specify the integration id ex. -i 123456
```
</CodeGroup>
</Tab>
<Tab title="Python OAuth2 Apps">
<CodeGroup>
```python get the entity and auth scheme for an app
from composio import ComposioToolSet, App

toolset = ComposioToolSet(entity_id="default")

app = App.Github
toolset = ComposioToolSet(entity_id="Jessica")

entity = toolset.get_entity()
schemes = toolset.get_auth_schemes(app=app)

print(schemes) # this should print all the auth schemes for the app
# filter next step based on the scheme
# some apps have multiple auth schemes ex. Github has OAuth2 and Basic Auth
```
</CodeGroup>

Complete Authentication process for OAuth2 application.
from composio.client.exceptions import NoItemsFound

<CodeGroup>
```python Complete Auth for OAuth2
try:
entity.get_connection(app=App.GITHUB)

print(f"Entity {entity_id} is already authenticated with GitHub")
print(f"User {entity_id} is already authenticated with GitHub")

except NoItemsFound as e:

# Create a request to initiate connection
request = entity.initiate_connection(App.Github, redirect_url="https://google.com")
request = entity.initiate_connection(App.GITHUB, redirect_url="https://google.com")

print(
f"Please authenticate {App.GITHUB} in the browser and come back here. URL: {request.redirectUrl}"
)

# Poll until the connection is active
connected_account = request.wait_until_active(client=composio_client, timeout=100)

# also possible to check on redirect url
# connected_account = entity.get_connection(app=App.GITHUB)

except Exception as e:
print(e)

```
</CodeGroup>

</Tab>
<Tab title="Python Non OAuth2 Apps">
<CodeGroup>
Expand All @@ -144,17 +57,7 @@ toolset = ComposioToolSet(entity_id="default")
app = App.SERPAPI

entity = toolset.get_entity()
schemes = toolset.get_auth_schemes(app=app)

print(schemes) # this should print all the auth schemes for the app
# filter next step based on the scheme
# some apps have multiple auth schemes ex. Github has OAuth2 and Basic Auth
```
</CodeGroup>
Complete Authentication process for non OAuth2 application.

<CodeGroup>
```python Complete Auth for Other Auth Schemes
try:
entity.get_connection(app=App.SERPAPI)

Expand All @@ -179,10 +82,6 @@ except NoItemsFound as e:
connected_account = connection_request.wait_until_active(client=toolset.client)

# use this connected_account to perform tasks on behalf of the entity

except Exception as e:
print(e)

```
</CodeGroup>

Expand Down Expand Up @@ -227,6 +126,42 @@ const connection = await entity.initiateConnection(
```
</CodeGroup>

</Tab>
<Tab title="CLI">
<CodeGroup>
```bash Adding a connection for an entity
composio add github -e default # replace `default` with the entity id

# you can also use -s to specify scopes ex. -s "repo,user"
# you can also use -i to specify the integration id ex. -i 123456
```
</CodeGroup>
</Tab>
<Tab title="Via Dashboard">
The Composio dashboard primarily serves as a tool for quickly verifying your integration and trying new connections for initial testing.
For deploying in a production environment, utilize the SDK or API methods.
<div
style={{
width: '100%',
position: 'relative',
paddingTop: '56.25%',
}}>
<iframe
src="https://app.supademo.com/embed/cly1z8i4g0lwy149zfx6h4ee2"
frameBorder="0"
title="Direct Action Execution"
allow="clipboard-write"
webkitallowfullscreen="true"
mozallowfullscreen="true"
allowfullscreen
style={{
position: 'absolute',
top: 0,left: 0, width: '100%', height: '100%',
border: '3px solid #5E43CE',
borderRadius: '10px',
}}/>
</div>

</Tab>
</Tabs>

Expand Down
Loading

0 comments on commit 945fd43

Please sign in to comment.